{"files":{"SKILL.md":"---\nname: forem-api-v1\ndescription: \"Forem API V1 API skill. Use when working with Forem API V1 for api. Covers 131 endpoints.\"\nversion: 1.0.0\ngenerator: lapsh\n---\n\n# Forem API V1\nAPI version: 1.0.0\n\n## Auth\nApiKey api-key in header\n\n## Base URL\nhttps://dev.to\n\n## Setup\n1. Set your API key in the appropriate header\n2. GET /api/agent_sessions -- list the authenticated user's agent sessions\n3. POST /api/agent_sessions -- create first agent_session\n\n## Endpoints\n131 endpoints across 1 group. See references/api-spec.lap for full details.\n\n### Api\n| Method | Path | Description |\n|--------|------|-------------|\n| GET | /api/agent_sessions | list the authenticated user's agent sessions |\n| POST | /api/agent_sessions | upload a new agent session |\n| GET | /api/agent_sessions/{id} | show details for an agent session |\n| GET | /api/analytics/totals | Retrieve analytics totals |\n| GET | /api/analytics/historical | Retrieve historical analytics |\n| GET | /api/analytics/past_day | Retrieve analytics for the past day |\n| GET | /api/analytics/referrers | Retrieve referrer analytics |\n| GET | /api/analytics/top_contributors | Retrieve top contributors analytics |\n| GET | /api/analytics/follower_engagement | Retrieve follower engagement analytics |\n| GET | /api/analytics/dashboard | Retrieve dashboard analytics bundle |\n| GET | /api/analytics/heatmap | Retrieve heatmap activity |\n| POST | /api/articles | Publish article |\n| GET | /api/articles | Published articles |\n| GET | /api/articles/search | Search for articles |\n| GET | /api/articles/latest | Published articles sorted by published date |\n| GET | /api/articles/{id} | Published article by id |\n| PUT | /api/articles/{id} | Update an article by id |\n| GET | /api/articles/{username}/{slug} | Published article by path |\n| GET | /api/articles/me | User's articles |\n| GET | /api/articles/me/published | User's published articles |\n| GET | /api/articles/me/unpublished | User's unpublished articles |\n| GET | /api/articles/me/all | User's all articles |\n| PUT | /api/articles/{id}/unpublish | Unpublish an article |\n| GET | /api/articles/semantic_search | Perform a semantic fuzzy search on articles |\n| GET | /api/segments | Manually managed audience segments |\n| POST | /api/segments | Create a manually managed audience segment |\n| GET | /api/segments/{id} | A manually managed audience segment |\n| DELETE | /api/segments/{id} | Delete a manually managed audience segment |\n| GET | /api/segments/{id}/users | Users in a manually managed audience segment |\n| PUT | /api/segments/{id}/add_users | Add users to a manually managed audience segment |\n| PUT | /api/segments/{id}/remove_users | Remove users from a manually managed audience segment |\n| GET | /api/badge_achievements | Retrieve all badge achievements |\n| POST | /api/badge_achievements | Create a badge achievement |\n| GET | /api/badge_achievements/{id} | Retrieve a badge achievement's details |\n| DELETE | /api/badge_achievements/{id} | Delete a badge achievement |\n| GET | /api/badges | Retrieve all badges |\n| POST | /api/badges | Create a badge |\n| GET | /api/badges/{id} | Retrieve a badge's details |\n| PATCH | /api/badges/{id} | Update a badge |\n| DELETE | /api/badges/{id} | Delete a badge |\n| GET | /api/billboards | Billboards |\n| POST | /api/billboards | Create a billboard |\n| GET | /api/billboards/{id} | A billboard (by id) |\n| PUT | /api/billboards/{id} | Update a billboard by ID |\n| PUT | /api/billboards/{id}/unpublish | Unpublish a billboard |\n| GET | /api/comments | Comments |\n| GET | /api/comments/{id} | Comment by id |\n| GET | /api/concepts | Retrieve all accessible concepts |\n| GET | /api/concepts/{id} | Retrieve details of a concept |\n| PATCH | /api/concepts/{id} | Update a concept's metadata |\n| GET | /api/concepts/{id}/articles | Retrieve articles mapped to a concept |\n| GET | /api/admin/concepts | Retrieve all concepts (Admin) |\n| POST | /api/admin/concepts | Create a concept (Admin) |\n| GET | /api/admin/concepts/{id} | Retrieve concept detail (Admin) |\n| PATCH | /api/admin/concepts/{id} | Update a concept (Admin) |\n| DELETE | /api/admin/concepts/{id} | Delete a concept (Admin) |\n| POST | /api/admin/concepts/{id}/trigger_lookback | Trigger concept lookback backfill (Admin) |\n| GET | /api/concepts/search | Perform a semantic fuzzy search on concepts |\n| PATCH | /api/feedback_messages/{id} | Update a feedback message's status (Admin) |\n| GET | /api/follows/tags | Followed Tags |\n| GET | /api/followers/users | Followers |\n| POST | /api/follows | Follow users or organizations |\n| GET | /api/health_checks/app | Check app health |\n| GET | /api/health_checks/database | Check database connection |\n| GET | /api/health_checks/cache | Check cache connection |\n| GET | /api/instance | Retrieve instance configuration details |\n| GET | /api/organizations/{username} | An organization (by username) |\n| GET | /api/organizations/{organization_id_or_username}/users | Organization's users |\n| GET | /api/organizations/{organization_id_or_username}/articles | Organization's Articles |\n| GET | /api/organizations | Organizations |\n| POST | /api/organizations | Create an Organization |\n| GET | /api/organizations/{id} | An organization (by id) |\n| PUT | /api/organizations/{id} | Update an organization by id |\n| DELETE | /api/organizations/{id} | Delete an Organization by id |\n| GET | /api/pages | show details for all pages |\n| POST | /api/pages | pages |\n| GET | /api/pages/{id} | show details for a page |\n| PUT | /api/pages/{id} | update details for a page |\n| DELETE | /api/pages/{id} | remove a page |\n| GET | /api/podcast_episodes | Podcast Episodes |\n| GET | /api/profile_images/{username} | A Users or organizations profile image |\n| POST | /api/reactions/toggle | toggle reaction |\n| POST | /api/reactions | create reaction |\n| GET | /api/readinglist | Readinglist |\n| GET | /api/recommended_articles_lists | Retrieve all recommended articles lists |\n| POST | /api/recommended_articles_lists | Create or update a recommended articles list |\n| GET | /api/recommended_articles_lists/{id} | Retrieve details of a recommended articles list |\n| PATCH | /api/recommended_articles_lists/{id} | Update a recommended articles list |\n| GET | /api/admin/request_redirects | Retrieve all request redirects (Admin) |\n| POST | /api/admin/request_redirects | Create a request redirect (Admin) |\n| GET | /api/admin/request_redirects/{id} | Retrieve a request redirect's details (Admin) |\n| PATCH | /api/admin/request_redirects/{id} | Update a request redirect (Admin) |\n| DELETE | /api/admin/request_redirects/{id} | Delete a request redirect (Admin) |\n| GET | /api/subforems | Retrieve all discoverable subforems |\n| GET | /api/surveys | List surveys |\n| POST | /api/surveys | Create a survey |\n| GET | /api/surveys/{id_or_slug} | A survey with polls |\n| PATCH | /api/surveys/{id_or_slug} | Update a survey |\n| DELETE | /api/surveys/{id_or_slug} | Delete a survey |\n| GET | /api/surveys/{id_or_slug}/poll_votes | Survey poll votes |\n| GET | /api/surveys/{id_or_slug}/poll_text_responses | Survey poll text responses |\n| GET | /api/tags | Tags |\n| GET | /api/trends | Trends |\n| GET | /api/trends/{id_or_slug} | A Trend |\n| GET | /api/trends/{trend_id_or_slug}/articles | Articles in a Trend |\n| PUT | /api/users/{id}/suspend | Suspend a User |\n| PUT | /api/users/{id}/limited | Add limited role for a User |\n| DELETE | /api/users/{id}/limited | Remove limited for a User |\n| PUT | /api/users/{id}/spam | Add spam role for a User |\n| DELETE | /api/users/{id}/spam | Remove spam role from a User |\n| PUT | /api/users/{id}/trusted | Add trusted role for a User |\n| DELETE | /api/users/{id}/trusted | Remove trusted role from a User |\n| GET | /api/users/me | The authenticated user |\n| GET | /api/users/{id} | A User |\n| GET | /api/users/search | Search for users |\n| PUT | /api/users/{id}/unpublish | Unpublish a User's Articles and Comments |\n| POST | /api/admin/users | Invite a User |\n| GET | /api/admin/users | List all users (Admin) |\n| GET | /api/admin/users/{id} | Get user detail (Admin) |\n| PATCH | /api/admin/users/{id} | Update user profile (Admin) |\n| PUT | /api/admin/users/{id}/email | Update user email (Admin) |\n| PUT | /api/admin/users/{id}/status | Update user moderation status (Admin) |\n| PUT | /api/admin/users/{id}/notification_settings | Update user notification settings (Admin) |\n| POST | /api/admin/users/{id}/merge | Merge user into another (Admin) |\n| GET | /api/admin/users/{user_id}/notes | List notes for a user (Admin) |\n| POST | /api/admin/users/{user_id}/notes | Add a note to a user (Admin) |\n| GET | /api/admin/users/{user_id}/identities | List identities for a user (Admin) |\n| POST | /api/admin/users/{user_id}/identities | Link an identity to a user (Admin) |\n| DELETE | /api/admin/users/{user_id}/identities/{id} | Unlink an identity from a user (Admin) |\n| POST | /api/admin/users/identities/bulk | Bulk link identities (Admin) |\n| GET | /api/videos | Articles with a video |\n\n## Common Questions\nMatch user requests to endpoints in references/api-spec.lap. Key patterns:\n- \"List all agent_sessions?\" -> GET /api/agent_sessions\n- \"Create a agent_session?\" -> POST /api/agent_sessions\n- \"Get agent_session details?\" -> GET /api/agent_sessions/{id}\n- \"List all totals?\" -> GET /api/analytics/totals\n- \"List all historical?\" -> GET /api/analytics/historical\n- \"List all past_day?\" -> GET /api/analytics/past_day\n- \"List all referrers?\" -> GET /api/analytics/referrers\n- \"List all top_contributors?\" -> GET /api/analytics/top_contributors\n- \"List all follower_engagement?\" -> GET /api/analytics/follower_engagement\n- \"List all dashboard?\" -> GET /api/analytics/dashboard\n- \"List all heatmap?\" -> GET /api/analytics/heatmap\n- \"Create a article?\" -> POST /api/articles\n- \"List all articles?\" -> GET /api/articles\n- \"Search search?\" -> GET /api/articles/search\n- \"List all latest?\" -> GET /api/articles/latest\n- \"Get article details?\" -> GET /api/articles/{id}\n- \"Update a article?\" -> PUT /api/articles/{id}\n- \"List all me?\" -> GET /api/articles/me\n- \"List all published?\" -> GET /api/articles/me/published\n- \"List all unpublished?\" -> GET /api/articles/me/unpublished\n- \"List all all?\" -> GET /api/articles/me/all\n- \"Search semantic_search?\" -> GET /api/articles/semantic_search\n- \"List all segments?\" -> GET /api/segments\n- \"Create a segment?\" -> POST /api/segments\n- \"Get segment details?\" -> GET /api/segments/{id}\n- \"Delete a segment?\" -> DELETE /api/segments/{id}\n- \"List all users?\" -> GET /api/segments/{id}/users\n- \"List all badge_achievements?\" -> GET /api/badge_achievements\n- \"Create a badge_achievement?\" -> POST /api/badge_achievements\n- \"Get badge_achievement details?\" -> GET /api/badge_achievements/{id}\n- \"Delete a badge_achievement?\" -> DELETE /api/badge_achievements/{id}\n- \"List all badges?\" -> GET /api/badges\n- \"Create a badge?\" -> POST /api/badges\n- \"Get badge details?\" -> GET /api/badges/{id}\n- \"Partially update a badge?\" -> PATCH /api/badges/{id}\n- \"Delete a badge?\" -> DELETE /api/badges/{id}\n- \"List all billboards?\" -> GET /api/billboards\n- \"Create a billboard?\" -> POST /api/billboards\n- \"Get billboard details?\" -> GET /api/billboards/{id}\n- \"Update a billboard?\" -> PUT /api/billboards/{id}\n- \"List all comments?\" -> GET /api/comments\n- \"Get comment details?\" -> GET /api/comments/{id}\n- \"List all concepts?\" -> GET /api/concepts\n- \"Get concept details?\" -> GET /api/concepts/{id}\n- \"Partially update a concept?\" -> PATCH /api/concepts/{id}\n- \"Create a concept?\" -> POST /api/admin/concepts\n- \"Delete a concept?\" -> DELETE /api/admin/concepts/{id}\n- \"Create a trigger_lookback?\" -> POST /api/admin/concepts/{id}/trigger_lookback\n- \"Partially update a feedback_message?\" -> PATCH /api/feedback_messages/{id}\n- \"List all tags?\" -> GET /api/follows/tags\n- \"Create a follow?\" -> POST /api/follows\n- \"List all app?\" -> GET /api/health_checks/app\n- \"List all database?\" -> GET /api/health_checks/database\n- \"List all cache?\" -> GET /api/health_checks/cache\n- \"List all instance?\" -> GET /api/instance\n- \"Get organization details?\" -> GET /api/organizations/{username}\n- \"List all organizations?\" -> GET /api/organizations\n- \"Create a organization?\" -> POST /api/organizations\n- \"Update a organization?\" -> PUT /api/organizations/{id}\n- \"Delete a organization?\" -> DELETE /api/organizations/{id}\n- \"List all pages?\" -> GET /api/pages\n- \"Create a page?\" -> POST /api/pages\n- \"Get page details?\" -> GET /api/pages/{id}\n- \"Update a page?\" -> PUT /api/pages/{id}\n- \"Delete a page?\" -> DELETE /api/pages/{id}\n- \"List all podcast_episodes?\" -> GET /api/podcast_episodes\n- \"Get profile_image details?\" -> GET /api/profile_images/{username}\n- \"Create a toggle?\" -> POST /api/reactions/toggle\n- \"Create a reaction?\" -> POST /api/reactions\n- \"List all readinglist?\" -> GET /api/readinglist\n- \"Search recommended_articles_lists?\" -> GET /api/recommended_articles_lists\n- \"Create a recommended_articles_list?\" -> POST /api/recommended_articles_lists\n- \"Get recommended_articles_list details?\" -> GET /api/recommended_articles_lists/{id}\n- \"Partially update a recommended_articles_list?\" -> PATCH /api/recommended_articles_lists/{id}\n- \"List all request_redirects?\" -> GET /api/admin/request_redirects\n- \"Create a request_redirect?\" -> POST /api/admin/request_redirects\n- \"Get request_redirect details?\" -> GET /api/admin/request_redirects/{id}\n- \"Partially update a request_redirect?\" -> PATCH /api/admin/request_redirects/{id}\n- \"Delete a request_redirect?\" -> DELETE /api/admin/request_redirects/{id}\n- \"List all subforems?\" -> GET /api/subforems\n- \"List all surveys?\" -> GET /api/surveys\n- \"Create a survey?\" -> POST /api/surveys\n- \"Get survey details?\" -> GET /api/surveys/{id_or_slug}\n- \"Partially update a survey?\" -> PATCH /api/surveys/{id_or_slug}\n- \"Delete a survey?\" -> DELETE /api/surveys/{id_or_slug}\n- \"List all poll_votes?\" -> GET /api/surveys/{id_or_slug}/poll_votes\n- \"List all poll_text_responses?\" -> GET /api/surveys/{id_or_slug}/poll_text_responses\n- \"List all trends?\" -> GET /api/trends\n- \"Get trend details?\" -> GET /api/trends/{id_or_slug}\n- \"Get user details?\" -> GET /api/users/{id}\n- \"List all search?\" -> GET /api/users/search\n- \"Create a user?\" -> POST /api/admin/users\n- \"Partially update a user?\" -> PATCH /api/admin/users/{id}\n- \"Create a merge?\" -> POST /api/admin/users/{id}/merge\n- \"List all notes?\" -> GET /api/admin/users/{user_id}/notes\n- \"Create a note?\" -> POST /api/admin/users/{user_id}/notes\n- \"List all identities?\" -> GET /api/admin/users/{user_id}/identities\n- \"Create a identity?\" -> POST /api/admin/users/{user_id}/identities\n- \"Delete a identity?\" -> DELETE /api/admin/users/{user_id}/identities/{id}\n- \"Create a bulk?\" -> POST /api/admin/users/identities/bulk\n- \"List all videos?\" -> GET /api/videos\n- \"How to authenticate?\" -> See Auth section above\n\n## Response Tips\n- Check response schemas in references/api-spec.lap for field details\n- Paginated endpoints accept limit/offset or cursor parameters\n- Create/update endpoints return the modified resource on success\n- Error responses include status codes and descriptions in the spec\n\n## References\n- Full spec: See references/api-spec.lap for complete endpoint details, parameter tables, and response schemas\n\n> Generated from the official API spec by [LAP](https://lap.sh)\n","references/api-spec.lap":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Forem API V1\n@base https://dev.to\n@version 1.0.0\n@auth ApiKey api-key in header\n@endpoints 131\n@hint download_for_search\n@toc api(131)\n\n@endpoint GET /api/agent_sessions\n@desc list the authenticated user's agent sessions\n@returns(200) successful\n@errors {401: unauthorized}\n\n@endpoint POST /api/agent_sessions\n@desc upload a new agent session\n@required {curated_data: str # JSON string of curated session data with messages array and metadata.}\n@optional {title: str # Title for the session (auto-generated if omitted), s3_key: str # S3 object key from presign endpoint (optional)., tool_name: str(claude_code/codex/gemini_cli/github_copilot/opencode/pi) # Tool that produced the session (e.g. claude_code, codex).}\n@returns(201) {id: int(int64), slug: str, title: str, tool_name: str, total_messages: int(int32), published: bool, created_at: str(date-time), updated_at: str(date-time), url: str(url)} # created\n@errors {401: unauthorized, 422: unprocessable}\n\n@endpoint GET /api/agent_sessions/{id}\n@desc show details for an agent session\n@required {id: str # The unique slug or ID of the agent session.}\n@returns(200) {id: int(int64), slug: str, title: str, tool_name: str, total_messages: int(int32), curated_count: int(int32), published: bool, metadata: map?, messages: [map], slices: [map], created_at: str(date-time), updated_at: str(date-time), url: str(url)} # successful\n@errors {401: unauthorized, 404: not found}\n\n@endpoint GET /api/analytics/totals\n@desc Retrieve analytics totals\n@optional {article_id: int # Optional ID to limit totals to a single article., organization_id: int # Optional ID to limit totals to an organization's articles.}\n@returns(200) successful\n\n@endpoint GET /api/analytics/historical\n@desc Retrieve historical analytics\n@required {start: str # Start date (YYYY-MM-DD format).}\n@optional {end: str # End date (YYYY-MM-DD format)., article_id: int # Limit stats to a single article., organization_id: int # Limit stats to an organization's articles.}\n@returns(200) successful\n\n@endpoint GET /api/analytics/past_day\n@desc Retrieve analytics for the past day\n@optional {article_id: int, organization_id: int}\n@returns(200) successful\n\n@endpoint GET /api/analytics/referrers\n@desc Retrieve referrer analytics\n@optional {start: str, end: str, article_id: int, organization_id: int}\n@returns(200) successful\n\n@endpoint GET /api/analytics/top_contributors\n@desc Retrieve top contributors analytics\n@optional {start: str, end: str, article_id: int, organization_id: int}\n@returns(200) successful\n\n@endpoint GET /api/analytics/follower_engagement\n@desc Retrieve follower engagement analytics\n@optional {start: str, end: str}\n@returns(200) successful\n\n@endpoint GET /api/analytics/dashboard\n@desc Retrieve dashboard analytics bundle\n@optional {start: str, end: str, article_id: int, organization_id: int}\n@returns(200) successful\n\n@endpoint GET /api/analytics/heatmap\n@desc Retrieve heatmap activity\n@optional {end: str}\n@returns(200) successful\n\n@endpoint POST /api/articles\n@desc Publish article\n@optional {article: map{title: str, body_markdown: str, published: bool, series: str, main_image: str, canonical_url: str, description: str, tags: str, organization_id: int}}\n@returns(201) An Article\n@errors {401: Unauthorized, 422: Unprocessable Entity}\n\n@endpoint GET /api/articles\n@desc Published articles\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable., tag: str # Using this parameter will retrieve articles that contain the requested tag. Articles will be ordered by descending popularity.This parameter can be used in conjuction with `top`., tags: str # Using this parameter will retrieve articles with any of the comma-separated tags. Articles will be ordered by descending popularity., tags_exclude: str # Using this parameter will retrieve articles that do _not_ contain _any_ of comma-separated tags. Articles will be ordered by descending popularity., username: str # Using this parameter will retrieve articles belonging             to a User or Organization ordered by descending publication date.             If `state=all` the number of items returned will be `1000` instead of the default `30`.             This parameter can be used in conjuction with `state`., state: str(fresh/rising/all) # Using this parameter will allow the client to check which articles are fresh or rising.             If `state=fresh` the server will return fresh articles.             If `state=rising` the server will return rising articles.             This param can be used in conjuction with `username`, only if set to `all`., top: int(int32) # Using this parameter will allow the client to return the most popular articles in the last `N` days. `top` indicates the number of days since publication of the articles returned. This param can be used in conjuction with `tag`., collection_id: int(int32) # Adding this will allow the client to return the list of articles belonging to the requested collection, ordered by ascending publication date.}\n@returns(200) A List of Articles\n\n@endpoint GET /api/articles/search\n@desc Search for articles\n@optional {q: str # The search query term. Matches against article titles, tags, and body content., top: int # Restricts search results to articles published within the last `N` days., page: int # Pagination page index., per_page: int # The number of items to return per page.}\n@returns(200) A List of Articles\n\n@endpoint GET /api/articles/latest\n@desc Published articles sorted by published date\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) A List of Articles\n\n@endpoint GET /api/articles/{id}\n@desc Published article by id\n@required {id: int # The unique numerical ID of the published article.}\n@returns(200) An Article\n@errors {404: Article Not Found}\n\n@endpoint PUT /api/articles/{id}\n@desc Update an article by id\n@required {id: int(int32) # The unique numerical ID of the article to update.}\n@optional {article: map{title: str, body_markdown: str, published: bool, series: str, main_image: str, canonical_url: str, description: str, tags: str, organization_id: int}}\n@returns(200) An Article\n@errors {401: Unauthorized, 404: Article Not Found, 422: Unprocessable Entity}\n\n@endpoint GET /api/articles/{username}/{slug}\n@desc Published article by path\n@required {username: str # The username of the article's author or organization., slug: str # The URL-friendly slug of the article (e.g. `my-first-post-1234`).}\n@returns(200) An Article\n@errors {404: Article Not Found}\n\n@endpoint GET /api/articles/me\n@desc User's articles\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) A List of the authenticated user's Articles\n@errors {401: Unauthorized}\n\n@endpoint GET /api/articles/me/published\n@desc User's published articles\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) A List of the authenticated user's Articles\n@errors {401: Unauthorized}\n\n@endpoint GET /api/articles/me/unpublished\n@desc User's unpublished articles\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) A List of the authenticated user's Articles\n@errors {401: Unauthorized}\n\n@endpoint GET /api/articles/me/all\n@desc User's all articles\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) A List of the authenticated user's Articles\n@errors {401: Unauthorized}\n\n@endpoint PUT /api/articles/{id}/unpublish\n@desc Unpublish an article\n@required {id: int(int32) # The ID of the article to unpublish.}\n@optional {note: str # Content for the note that's created along with unpublishing}\n@returns(204) Article successfully unpublished\n@errors {401: Unauthorized, 404: Article Not Found}\n\n@endpoint GET /api/articles/semantic_search\n@desc Perform a semantic fuzzy search on articles\n@required {q: str # The search query term to match semantically.}\n@optional {per_page: int # Limit of articles returned (default 10, max 50)., page: int # Pagination page index., threshold: num # Optional cosine distance threshold (between 0.0 and 2.0) to filter results.}\n@returns(200) successful\n@errors {400: bad request, 401: unauthorized}\n\n@endpoint GET /api/segments\n@desc Manually managed audience segments\n@optional {per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) A List of manually managed audience segments\n@errors {401: Unauthorized}\n\n@endpoint POST /api/segments\n@desc Create a manually managed audience segment\n@returns(201) A manually managed audience segment\n@errors {401: Unauthorized}\n\n@endpoint GET /api/segments/{id}\n@desc A manually managed audience segment\n@required {id: int(int32) # Unique segment numerical ID.}\n@returns(200) The audience segment\n@errors {401: Unauthorized, 404: Audience Segment Not Found}\n\n@endpoint DELETE /api/segments/{id}\n@desc Delete a manually managed audience segment\n@required {id: int(int32) # Unique segment numerical ID.}\n@returns(200) The deleted audience segment\n@errors {401: Unauthorized, 404: Audience Segment Not Found, 409: Audience segment could not be deleted}\n\n@endpoint GET /api/segments/{id}/users\n@desc Users in a manually managed audience segment\n@required {id: int(int32) # Unique segment numerical ID.}\n@optional {per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) A List of users in the audience segment\n@errors {401: Unauthorized, 404: Audience Segment Not Found}\n\n@endpoint PUT /api/segments/{id}/add_users\n@desc Add users to a manually managed audience segment\n@required {id: int(int32) # Unique segment numerical ID.}\n@optional {user_ids: [int]}\n@returns(200) Result of adding the users to the segment.\n@errors {401: Unauthorized, 404: Audience Segment Not Found, 422: Unprocessable Entity}\n\n@endpoint PUT /api/segments/{id}/remove_users\n@desc Remove users from a manually managed audience segment\n@required {id: int(int32) # Unique segment numerical ID.}\n@optional {user_ids: [int]}\n@returns(200) Result of removing the users to the segment.\n@errors {401: Unauthorized, 404: Audience Segment Not Found, 422: Unprocessable Entity}\n\n@endpoint GET /api/badge_achievements\n@desc Retrieve all badge achievements\n@optional {page: int # Pagination page index.}\n@returns(200) successful\n\n@endpoint POST /api/badge_achievements\n@desc Create a badge achievement\n@optional {badge_achievement: map{user_id!: int, badge_id!: int, rewarding_context_message_markdown: str, include_default_description: bool}}\n@returns(201) {id: int(int64), user_id: int(int64), badge_id: int(int64), rewarding_context_message_markdown: str?, include_default_description: bool, created_at: str(date-time), updated_at: str(date-time)} # created\n\n@endpoint GET /api/badge_achievements/{id}\n@desc Retrieve a badge achievement's details\n@required {id: int # Badge achievement unique ID.}\n@returns(200) {id: int(int64), user_id: int(int64), badge_id: int(int64), rewarding_context_message_markdown: str?, include_default_description: bool, created_at: str(date-time), updated_at: str(date-time)} # successful\n\n@endpoint DELETE /api/badge_achievements/{id}\n@desc Delete a badge achievement\n@required {id: int # Badge achievement unique ID to delete.}\n@returns(204) no content\n\n@endpoint GET /api/badges\n@desc Retrieve all badges\n@optional {page: int # Pagination page index.}\n@returns(200) successful\n\n@endpoint POST /api/badges\n@desc Create a badge\n@optional {badge: map{title!: str, description!: str, remote_badge_image_url!: str, credits_awarded: int, allow_multiple_awards: bool}}\n@returns(201) {id: int(int64), title: str, slug: str, description: str, badge_image: map?{url: str}, credits_awarded: int, allow_multiple_awards: bool, created_at: str(date-time), updated_at: str(date-time)} # created\n\n@endpoint GET /api/badges/{id}\n@desc Retrieve a badge's details\n@required {id: int # Unique badge ID.}\n@returns(200) {id: int(int64), title: str, slug: str, description: str, badge_image: map?{url: str}, credits_awarded: int, allow_multiple_awards: bool, created_at: str(date-time), updated_at: str(date-time)} # successful\n\n@endpoint PATCH /api/badges/{id}\n@desc Update a badge\n@required {id: int # Unique badge ID to update.}\n@optional {badge: map{title: str, description: str, credits_awarded: int, allow_multiple_awards: bool}}\n@returns(200) {id: int(int64), title: str, slug: str, description: str, badge_image: map?{url: str}, credits_awarded: int, allow_multiple_awards: bool, created_at: str(date-time), updated_at: str(date-time)} # successful\n\n@endpoint DELETE /api/badges/{id}\n@desc Delete a badge\n@required {id: int # Unique badge ID to delete.}\n@returns(204) no content\n\n@endpoint GET /api/billboards\n@desc Billboards\n@returns(200) successful\n@errors {401: unauthorized}\n\n@endpoint POST /api/billboards\n@desc Create a billboard\n@returns(201) A billboard\n@errors {401: unauthorized, 422: unprocessable}\n\n@endpoint GET /api/billboards/{id}\n@desc A billboard (by id)\n@required {id: int(int32) # The ID of the billboard.}\n@returns(200) successful\n@errors {401: unauthorized, 404: Unknown Billboard ID}\n\n@endpoint PUT /api/billboards/{id}\n@desc Update a billboard by ID\n@required {id: int(int32) # The ID of the billboard to update.}\n@returns(200) successful\n@errors {401: unauthorized, 404: not found}\n\n@endpoint PUT /api/billboards/{id}/unpublish\n@desc Unpublish a billboard\n@required {id: int(int32) # The ID of the billboard to unpublish.}\n@returns(204) no content\n@errors {401: unauthorized, 404: not found}\n\n@endpoint GET /api/comments\n@desc Comments\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable., a_id: str # Article identifier. Provide this to fetch comments belonging to a specific article., p_id: str # Podcast Episode identifier. Provide this to fetch comments belonging to a specific podcast episode., page: str # Pagination page index for top-level comments.}\n@returns(200) A List of Comments\n@errors {404: Resource Not Found}\n\n@endpoint GET /api/comments/{id}\n@desc Comment by id\n@required {id: str # Comment identifier (the unique alpha-numeric `id_code` of the comment).}\n@returns(200) A List of the Comments\n@errors {404: Comment Not Found}\n\n@endpoint GET /api/concepts\n@desc Retrieve all accessible concepts\n@optional {page: int # Pagination page index., per_page: int # Number of items to return per page., days: int # Number of days of activity to aggregate for computing the concept popularity/trend score (default is 7 days).}\n@returns(200) successful\n@errors {401: unauthorized}\n\n@endpoint GET /api/concepts/{id}\n@desc Retrieve details of a concept\n@required {id: int # Unique concept numerical ID.}\n@optional {days: int # Number of days of activity to aggregate for the concept popularity/trend score.}\n@returns(200) {id: int(int64), name: str, slug: str, description: str?, parent_id: int(int64)?, score: num(float), similarity_threshold: num(float)?, created_at: str(date-time), updated_at: str(date-time), daily_metrics: [map], top_articles: [map]} # successful\n@errors {401: unauthorized}\n\n@endpoint PATCH /api/concepts/{id}\n@desc Update a concept's metadata\n@required {id: int # Unique concept numerical ID.}\n@optional {concept: map{score: num, description: str, similarity_threshold: num}}\n@returns(200) {id: int(int64), name: str, slug: str, description: str?, parent_id: int(int64)?, score: num(float), similarity_threshold: num(float)?, created_at: str(date-time), updated_at: str(date-time), daily_metrics: [map], top_articles: [map]} # successful\n\n@endpoint GET /api/concepts/{id}/articles\n@desc Retrieve articles mapped to a concept\n@required {id: int # Unique concept numerical ID.}\n@optional {sort: str # Sorting criteria: `score` or default., page: int # Pagination page index., per_page: int # Number of items to return per page.}\n@returns(200) successful\n\n@endpoint GET /api/admin/concepts\n@desc Retrieve all concepts (Admin)\n@optional {page: int, per_page: int}\n@returns(200) successful\n\n@endpoint POST /api/admin/concepts\n@desc Create a concept (Admin)\n@optional {concept: map{name!: str, description: str, parent_id: int, similarity_threshold: num, score: num}}\n@returns(201) {id: int(int64), name: str, slug: str, description: str?, parent_id: int(int64)?, score: num(float), similarity_threshold: num(float)?, created_at: str(date-time), updated_at: str(date-time), daily_metrics: [map], top_articles: [map]} # created\n\n@endpoint GET /api/admin/concepts/{id}\n@desc Retrieve concept detail (Admin)\n@required {id: int}\n@returns(200) {id: int(int64), name: str, slug: str, description: str?, parent_id: int(int64)?, score: num(float), similarity_threshold: num(float)?, created_at: str(date-time), updated_at: str(date-time), daily_metrics: [map], top_articles: [map]} # successful\n\n@endpoint PATCH /api/admin/concepts/{id}\n@desc Update a concept (Admin)\n@required {id: int}\n@optional {concept: map{name: str, description: str, parent_id: int, similarity_threshold: num, score: num}}\n@returns(200) {id: int(int64), name: str, slug: str, description: str?, parent_id: int(int64)?, score: num(float), similarity_threshold: num(float)?, created_at: str(date-time), updated_at: str(date-time), daily_metrics: [map], top_articles: [map]} # successful\n\n@endpoint DELETE /api/admin/concepts/{id}\n@desc Delete a concept (Admin)\n@required {id: int}\n@returns(204) no content\n\n@endpoint POST /api/admin/concepts/{id}/trigger_lookback\n@desc Trigger concept lookback backfill (Admin)\n@required {id: int, days: int}\n@returns(200) successful\n\n@endpoint GET /api/concepts/search\n@desc Perform a semantic fuzzy search on concepts\n@required {q: str # The search query term to match semantically.}\n@optional {per_page: int # Limit of concepts returned (default 10, max 50)., threshold: num # Optional cosine distance threshold (between 0.0 and 2.0) to filter results.}\n@returns(200) successful\n@errors {400: bad request, 401: unauthorized}\n\n@endpoint PATCH /api/feedback_messages/{id}\n@desc Update a feedback message's status (Admin)\n@required {id: int # Unique feedback message ID.}\n@optional {feedback_message: map{status!: str}}\n@returns(200) successful\n\n@endpoint GET /api/follows/tags\n@desc Followed Tags\n@returns(200) A List of followed tags\n@errors {401: unauthorized}\n\n@endpoint GET /api/followers/users\n@desc Followers\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable., sort: str # Specifies the sort order for the follow relationship created_at field. Use `created_at` for chronological (oldest first) or `-created_at` for reverse chronological (newest first).}\n@returns(200) A List of followers\n@errors {401: unauthorized}\n\n@endpoint POST /api/follows\n@desc Follow users or organizations\n@optional {user_ids: [int], organization_ids: [int]}\n@returns(200) {outcome: str} # successful\n\n@endpoint GET /api/health_checks/app\n@desc Check app health\n@optional {health-check-token: str # Access token required if token-based security is enabled in settings for health checks.}\n@returns(200) successful\n\n@endpoint GET /api/health_checks/database\n@desc Check database connection\n@optional {health-check-token: str # Access token required if token-based security is enabled in settings for health checks.}\n@returns(200) successful\n\n@endpoint GET /api/health_checks/cache\n@desc Check cache connection\n@optional {health-check-token: str # Access token required if token-based security is enabled in settings for health checks.}\n@returns(200) successful\n\n@endpoint GET /api/instance\n@desc Retrieve instance configuration details\n@returns(200) successful\n\n@endpoint GET /api/organizations/{username}\n@desc An organization (by username)\n@required {username: str # The unique slugified username of the organization (e.g. `github`).}\n@returns(200) An Organization\n@errors {404: Not Found}\n\n@endpoint GET /api/organizations/{organization_id_or_username}/users\n@desc Organization's users\n@required {organization_id_or_username: str # The organization's numerical ID or string username.}\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) An Organization's users (with ID)\n@errors {404: Not Found}\n\n@endpoint GET /api/organizations/{organization_id_or_username}/articles\n@desc Organization's Articles\n@required {organization_id_or_username: str # The organization's numerical ID or string username.}\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) An Organization's Articles (with ID)\n@errors {404: Not Found}\n\n@endpoint GET /api/organizations\n@desc Organizations\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=10 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) A list of all organizations\n\n@endpoint POST /api/organizations\n@desc Create an Organization\n@optional {type_of: str, username: str, name: str, summary: str, twitter_username: str, github_username: str, url: str, location: str, joined_at: str, tech_stack: str, tag_line: str, story: str}\n@returns(201) Successful\n@errors {401: Unauthorized, 422: Unprocessable Entity}\n\n@endpoint GET /api/organizations/{id}\n@desc An organization (by id)\n@required {id: int}\n@returns(200) An Organization\n@errors {404: Not Found}\n\n@endpoint PUT /api/organizations/{id}\n@desc Update an organization by id\n@required {id: int(int32) # The ID of the organization to update.}\n@optional {type_of: str, username: str, name: str, summary: str, twitter_username: str, github_username: str, url: str, location: str, joined_at: str, tech_stack: str, tag_line: str, story: str}\n@returns(200) An Organization\n@errors {401: Unauthorized, 404: organization Not Found, 422: Unprocessable Entity}\n\n@endpoint DELETE /api/organizations/{id}\n@desc Delete an Organization by id\n@required {id: int(int32) # The ID of the organization.}\n@returns(200) successful\n@errors {401: unauthorized}\n\n@endpoint GET /api/pages\n@desc show details for all pages\n@returns(200) successful\n\n@endpoint POST /api/pages\n@desc pages\n@optional {title: str # Title of the page, slug: str # Used to link to this page in URLs, must be unique and URL-safe, description: str # For internal use, helps similar pages from one another, body_markdown: str # The text (in markdown) of the page (required), body_json: str # For JSON pages, the JSON body, is_top_level_path: bool # If true, the page is available at '/{slug}' instead of '/page/{slug}', use with caution, template: str(contained/full_within_layout/nav_bar_included/json/css/txt)=contained # Controls what kind of layout the page is rendered in}\n@returns(200) successful\n@errors {401: unauthorized, 422: unprocessable}\n\n@endpoint GET /api/pages/{id}\n@desc show details for a page\n@required {id: int(int32) # The unique ID of the page.}\n@returns(200) {title: str, slug: str, description: str, body_markdown: str?, body_json: str?, is_top_level_path: bool, social_image: map?, template: str} # successful\n\n@endpoint PUT /api/pages/{id}\n@desc update details for a page\n@required {id: int(int32) # The ID of the page to update., title: str # Title of the page, slug: str # Used to link to this page in URLs, must be unique and URL-safe, description: str # For internal use, helps similar pages from one another, template: str(contained/full_within_layout/nav_bar_included/json/css/txt)=contained # Controls what kind of layout the page is rendered in}\n@optional {body_markdown: str # The text (in markdown) of the ad (required), body_json: str # For JSON pages, the JSON body, is_top_level_path: bool # If true, the page is available at '/{slug}' instead of '/page/{slug}', use with caution, social_image: map}\n@returns(200) {title: str, slug: str, description: str, body_markdown: str?, body_json: str?, is_top_level_path: bool, social_image: map?, template: str} # successful\n@errors {401: unauthorized, 422: unprocessable}\n\n@endpoint DELETE /api/pages/{id}\n@desc remove a page\n@required {id: int(int32) # The ID of the page to delete.}\n@returns(200) {title: str, slug: str, description: str, body_markdown: str?, body_json: str?, is_top_level_path: bool, social_image: map?, template: str} # successful\n@errors {401: unauthorized, 422: unprocessable}\n\n@endpoint GET /api/podcast_episodes\n@desc Podcast Episodes\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable., username: str # Filters episodes by the unique slug (username) of the podcast (e.g. 'codenewbie').}\n@returns(200) A List of Podcast episodes filtered by username\n@errors {404: Unknown Podcast username}\n\n@endpoint GET /api/profile_images/{username}\n@desc A Users or organizations profile image\n@required {username: str # The unique username of the target user or organization.}\n@returns(200) An object containing profile image details\n@errors {404: Resource Not Found}\n\n@endpoint POST /api/reactions/toggle\n@desc toggle reaction\n@required {category: str(like/unicorn/exploding_head/raised_hands/fire) # The type of reaction (e.g. `like` for standard likes, `unicorn` for outstanding posts, `save` for bookmarking to the reading list)., reactable_id: int(int32) # The unique numerical ID of the target resource (Article, Comment, or User) being reacted to., reactable_type: str(Comment/Article/User) # The class name of the target resource being reacted to (e.g. `Article`, `Comment`, `User`).}\n@returns(200) successful\n@errors {401: unauthorized}\n\n@endpoint POST /api/reactions\n@desc create reaction\n@required {category: str(like/unicorn/exploding_head/raised_hands/fire) # The type of reaction (e.g. `like` for standard likes, `unicorn` for outstanding posts, `save` for bookmarking to the reading list)., reactable_id: int(int32) # The unique numerical ID of the target resource (Article, Comment, or User) being reacted to., reactable_type: str(Comment/Article/User) # The class name of the target resource being reacted to (e.g. `Article`, `Comment`, `User`).}\n@returns(200) successful\n@errors {401: unauthorized}\n\n@endpoint GET /api/readinglist\n@desc Readinglist\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) A list of articles in the users readinglist\n@errors {401: Unauthorized}\n\n@endpoint GET /api/recommended_articles_lists\n@desc Retrieve all recommended articles lists\n@optional {page: int # Pagination page index., search: str # Search term to match against recommended list names.}\n@returns(200) successful\n\n@endpoint POST /api/recommended_articles_lists\n@desc Create or update a recommended articles list\n@required {placement_area: str, user_id: int}\n@optional {name: str, expires_at: str(date-time), article_ids: [int]}\n@returns(201) {id: int(int64), name: str, placement_area: str, expires_at: str(date-time)?, user_id: int(int64), article_ids: [int], created_at: str(date-time), updated_at: str(date-time)} # created\n\n@endpoint GET /api/recommended_articles_lists/{id}\n@desc Retrieve details of a recommended articles list\n@required {id: int # Unique list numeric ID.}\n@returns(200) {id: int(int64), name: str, placement_area: str, expires_at: str(date-time)?, user_id: int(int64), article_ids: [int], created_at: str(date-time), updated_at: str(date-time)} # successful\n\n@endpoint PATCH /api/recommended_articles_lists/{id}\n@desc Update a recommended articles list\n@required {id: int # Unique list numeric ID.}\n@optional {name: str, placement_area: str, expires_at: str(date-time), user_id: int, article_ids: [int]}\n@returns(200) {id: int(int64), name: str, placement_area: str, expires_at: str(date-time)?, user_id: int(int64), article_ids: [int], created_at: str(date-time), updated_at: str(date-time)} # successful\n\n@endpoint GET /api/admin/request_redirects\n@desc Retrieve all request redirects (Admin)\n@optional {page: int # Pagination page index., per_page: int # Number of items to return per page.}\n@returns(200) successful\n\n@endpoint POST /api/admin/request_redirects\n@desc Create a request redirect (Admin)\n@optional {request_redirect: map{original_url!: str, destination_url!: str, request_domain!: str}}\n@returns(201) {id: int(int64), original_url: str, destination_url: str, request_domain: str, created_at: str(date-time), updated_at: str(date-time)} # created\n\n@endpoint GET /api/admin/request_redirects/{id}\n@desc Retrieve a request redirect's details (Admin)\n@required {id: int # Unique redirect ID.}\n@returns(200) {id: int(int64), original_url: str, destination_url: str, request_domain: str, created_at: str(date-time), updated_at: str(date-time)} # successful\n\n@endpoint PATCH /api/admin/request_redirects/{id}\n@desc Update a request redirect (Admin)\n@required {id: int # Unique redirect ID to update.}\n@optional {request_redirect: map{original_url: str, destination_url: str, request_domain: str}}\n@returns(200) {id: int(int64), original_url: str, destination_url: str, request_domain: str, created_at: str(date-time), updated_at: str(date-time)} # successful\n\n@endpoint DELETE /api/admin/request_redirects/{id}\n@desc Delete a request redirect (Admin)\n@required {id: int # Unique redirect ID to delete.}\n@returns(204) no content\n\n@endpoint GET /api/subforems\n@desc Retrieve all discoverable subforems\n@returns(200) successful\n\n@endpoint GET /api/surveys\n@desc List surveys\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable., active: bool # Filter by active status. Omit to return all surveys.}\n@returns(200) A list of surveys\n@errors {401: Unauthorized}\n\n@endpoint POST /api/surveys\n@desc Create a survey\n@required {survey: map{title: str, survey_type_of: str, type_of: str, active: bool, display_title: bool, allow_resubmission: bool, daily_email_distributions: int(int32), extra_email_context_paragraph: str, target_response_count: int(int32), target_completion_date: str(date-time), polls: [map]}}\n@returns(201) Created\n@errors {401: Unauthorized, 422: Unprocessable Entity}\n\n@endpoint GET /api/surveys/{id_or_slug}\n@desc A survey with polls\n@required {id_or_slug: str # The ID or slug of the survey.}\n@returns(200) A survey with nested polls and options\n@errors {401: Unauthorized, 404: Not found}\n\n@endpoint PATCH /api/surveys/{id_or_slug}\n@desc Update a survey\n@required {id_or_slug: str # The ID or slug of the survey., survey: map{title: str, survey_type_of: str, type_of: str, active: bool, display_title: bool, allow_resubmission: bool, daily_email_distributions: int(int32), extra_email_context_paragraph: str, target_response_count: int(int32), target_completion_date: str(date-time), polls: [map]}}\n@returns(200) Successful\n@errors {401: Unauthorized, 404: Not Found, 422: Unprocessable Entity}\n\n@endpoint DELETE /api/surveys/{id_or_slug}\n@desc Delete a survey\n@required {id_or_slug: str # The ID or slug of the survey.}\n@returns(204) No Content\n@errors {401: Unauthorized, 404: Not Found, 422: Unprocessable Entity}\n\n@endpoint GET /api/surveys/{id_or_slug}/poll_votes\n@desc Survey poll votes\n@required {id_or_slug: str # The ID or slug of the survey.}\n@optional {per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable., after: int # Return only votes with an ID greater than this value.}\n@returns(200) Poll votes\n@errors {401: Unauthorized, 404: Not found}\n\n@endpoint GET /api/surveys/{id_or_slug}/poll_text_responses\n@desc Survey poll text responses\n@required {id_or_slug: str # The ID or slug of the survey.}\n@optional {per_page: int(int32)=30 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable., after: int # Return only text responses with an ID greater than this value.}\n@returns(200) Poll text responses\n@errors {401: Unauthorized, 404: Not found}\n\n@endpoint GET /api/tags\n@desc Tags\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=10 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) A List of all tags\n\n@endpoint GET /api/trends\n@desc Trends\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=10 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) A List of Trends\n\n@endpoint GET /api/trends/{id_or_slug}\n@desc A Trend\n@required {id_or_slug: str # The ID or slug of the trend to retrieve.}\n@returns(200) A Trend\n@errors {404: Trend Not Found}\n\n@endpoint GET /api/trends/{trend_id_or_slug}/articles\n@desc Articles in a Trend\n@required {trend_id_or_slug: str # The ID or slug of the trend to retrieve articles for.}\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=10 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) A List of Articles in the Trend\n@errors {404: Trend Not Found}\n\n@endpoint PUT /api/users/{id}/suspend\n@desc Suspend a User\n@required {id: int(int32) # The unique ID of the user to suspend.}\n@returns(204) User successfully unpublished\n@errors {401: Unauthorized, 404: Unknown User ID}\n\n@endpoint PUT /api/users/{id}/limited\n@desc Add limited role for a User\n@required {id: int(int32) # The ID of the user to limit.}\n@returns(204) User successfully limited\n@errors {401: Unauthorized, 404: Unknown User ID}\n\n@endpoint DELETE /api/users/{id}/limited\n@desc Remove limited for a User\n@required {id: int(int32) # The ID of the user to un-limit.}\n@returns(204) User successfully un-limited\n@errors {401: Unauthorized, 404: Unknown User ID}\n\n@endpoint PUT /api/users/{id}/spam\n@desc Add spam role for a User\n@required {id: int(int32) # The ID of the user to assign the spam role.}\n@returns(204) Spam role assigned to the user successfully\n@errors {401: Unauthorized, 404: Unknown User ID}\n\n@endpoint DELETE /api/users/{id}/spam\n@desc Remove spam role from a User\n@required {id: int(int32) # The ID of the user to remove the spam role from.}\n@returns(204) Successfully removed the spam role from a user\n@errors {401: Unauthorized, 404: Unknown User ID}\n\n@endpoint PUT /api/users/{id}/trusted\n@desc Add trusted role for a User\n@required {id: int(int32) # The ID of the user to assign the trusted role.}\n@returns(204) Trusted role assigned to the user successfully\n@errors {401: Unauthorized, 404: Unknown User ID}\n\n@endpoint DELETE /api/users/{id}/trusted\n@desc Remove trusted role from a User\n@required {id: int(int32) # The ID of the user to remove the trusted role from.}\n@returns(204) Successfully removed the trusted role from a user\n@errors {401: Unauthorized, 404: Unknown User ID}\n\n@endpoint GET /api/users/me\n@desc The authenticated user\n@returns(200) successful\n@errors {401: Unauthorized}\n\n@endpoint GET /api/users/{id}\n@desc A User\n@required {id: str # The user's unique numerical ID or string username.}\n@returns(200) successful\n\n@endpoint GET /api/users/search\n@desc Search for users\n@required {email: str # The exact email address of the user to search for.}\n@returns(200) {type_of: str, id: int(int64), username: str, name: str, summary: str?, twitter_username: str, github_username: str, email: str?, website_url: str?, location: str?, joined_at: str, profile_image: str, badge_ids: [int]} # successful\n\n@endpoint PUT /api/users/{id}/unpublish\n@desc Unpublish a User's Articles and Comments\n@required {id: int(int32) # The unique numerical ID of the user whose content will be unpublished.}\n@returns(204) User's articles and comments successfully unpublished\n\n@endpoint POST /api/admin/users\n@desc Invite a User\n@optional {email: str, name: str}\n@returns(200) Successful\n\n@endpoint GET /api/admin/users\n@desc List all users (Admin)\n@optional {page: int # Pagination page index., per_page: int # Number of items to return per page., email: str # Optional email search filter., username: str # Optional username search filter.}\n@returns(200) successful\n\n@endpoint GET /api/admin/users/{id}\n@desc Get user detail (Admin)\n@required {id: int # Unique user numeric ID.}\n@returns(200) successful\n\n@endpoint PATCH /api/admin/users/{id}\n@desc Update user profile (Admin)\n@required {id: int # Unique user ID to update.}\n@optional {name: str, username: str, summary: str, location: str, website_url: str}\n@returns(200) successful\n\n@endpoint PUT /api/admin/users/{id}/email\n@desc Update user email (Admin)\n@required {id: int # Unique user ID to update email for., email: str}\n@returns(200) successful\n\n@endpoint PUT /api/admin/users/{id}/status\n@desc Update user moderation status (Admin)\n@required {id: int # Unique user ID., status: str}\n@optional {note: str}\n@returns(200) successful\n\n@endpoint PUT /api/admin/users/{id}/notification_settings\n@desc Update user notification settings (Admin)\n@required {id: int # Unique user ID., notification_setting: map{email_newsletter: bool}}\n@returns(200) successful\n\n@endpoint POST /api/admin/users/{id}/merge\n@desc Merge user into another (Admin)\n@required {id: int # The duplicate user ID that will be deleted after contents merge., merge_user_id: int}\n@returns(200) successful\n\n@endpoint GET /api/admin/users/{user_id}/notes\n@desc List notes for a user (Admin)\n@required {user_id: int # User ID to fetch notes for.}\n@returns(200) successful\n\n@endpoint POST /api/admin/users/{user_id}/notes\n@desc Add a note to a user (Admin)\n@required {user_id: int # User ID to append the note to., content: str}\n@optional {reason: str}\n@returns(201) created\n\n@endpoint GET /api/admin/users/{user_id}/identities\n@desc List identities for a user (Admin)\n@required {user_id: int # User ID to fetch linked identities for.}\n@returns(200) successful\n\n@endpoint POST /api/admin/users/{user_id}/identities\n@desc Link an identity to a user (Admin)\n@required {user_id: int # User ID to bind identity to., provider: str, uid: str}\n@optional {username: str}\n@returns(201) created\n\n@endpoint DELETE /api/admin/users/{user_id}/identities/{id}\n@desc Unlink an identity from a user (Admin)\n@required {user_id: int # User ID., id: int # Identity ID to unlink.}\n@returns(204) no content\n\n@endpoint POST /api/admin/users/identities/bulk\n@desc Bulk link identities (Admin)\n@required {provider: str, identities: [map{user_id!: int, uid!: str}]}\n@returns(200) successful\n\n@endpoint GET /api/videos\n@desc Articles with a video\n@optional {page: int(int32)=1 # Pagination page, per_page: int(int32)=24 # Page size (the number of items to return per page). The default maximum value can be overridden by \"API_PER_PAGE_MAX\" environment variable.}\n@returns(200) A List of all articles with videos\n\n@end\n"}}