Forem API V1 (1.0.0)
Download OpenAPI specification:Download
Access Forem articles, users and other resources via API. For a real-world example of Forem in action, check out DEV. All endpoints can be accessed with the 'api-key' header and a accept header, but some of them are accessible publicly without authentication.
Dates and date times, unless otherwise specified, must be in
the [RFC 3339](https://tools.ietf.org/html/rfc3339) format.
Published articles
This endpoint allows the client to retrieve a list of articles.
"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.
By default it will return featured, published articles ordered by descending popularity.
It supports pagination, each page will contain 30
articles by default.
query Parameters
page | integer <int32> >= 1 Default: 1 Pagination page |
per_page | integer <int32> [ 1 .. 1000 ] Default: 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 | string Example: tag=discuss 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 |
tags | string Example: tags=javascript, css Using this parameter will retrieve articles with any of the comma-separated tags. Articles will be ordered by descending popularity. |
tags_exclude | string Example: tags_exclude=node, java Using this parameter will retrieve articles that do not contain any of comma-separated tags. Articles will be ordered by descending popularity. |
username | string Example: username=ben Using this parameter will retrieve articles belonging
to a User or Organization ordered by descending publication date.
If |
state | string Enum: "fresh" "rising" "all" Example: state=fresh Using this parameter will allow the client to check which articles are fresh or rising.
If |
top | integer <int32> >= 1 Example: top=2 Using this parameter will allow the client to return the most popular articles
in the last |
collection_id | integer <int32> Example: collection_id=99 Adding this will allow the client to return the list of articles belonging to the requested collection, ordered by ascending publication date. |
Responses
Response samples
- 200
[- {
- "type_of": "article",
- "id": 1544,
- "title": "The Line of Beauty172",
- "description": "Five dollar toast pour-over 8-bit gluten-free selvage try-hard. Stumptown listicle ennui plaid tacos...",
- "readable_publish_date": "Jan 12",
- "slug": "the-line-of-beauty172-39d8",
- "path": "/username382/the-line-of-beauty172-39d8",
- "comments_count": 0,
- "public_reactions_count": 0,
- "collection_id": null,
- "published_timestamp": "2023-01-11T16:00:22Z",
- "positive_reactions_count": 0,
- "created_at": "2023-01-11T16:00:22Z",
- "edited_at": null,
- "crossposted_at": null,
- "published_at": "2023-01-11T16:00:22Z",
- "last_comment_at": "2023-01-11T16:00:22Z",
- "reading_time_minutes": 1,
- "tag_list": [
- "discuss"
], - "tags": "discuss",
- "user": {
- "name": "Ira \"Tanna\" \\:/ West",
- "username": "username382",
- "twitter_username": "twitter382",
- "github_username": "github382",
- "user_id": 3620,
- "website_url": null,
- "profile_image": "/uploads/user/profile_image/3620/3b3f8cf9-6517-4a48-aa69-95eeaf8b0456.jpeg",
- "profile_image_90": "/uploads/user/profile_image/3620/3b3f8cf9-6517-4a48-aa69-95eeaf8b0456.jpeg"
}, - "organization": {
- "name": "Klocko and Sons",
- "username": "org67",
- "slug": "org67",
- "profile_image": "/uploads/organization/profile_image/666/5431d3e5-2222-4881-8108-adecceb1cf6f.png",
- "profile_image_90": "/uploads/organization/profile_image/666/5431d3e5-2222-4881-8108-adecceb1cf6f.png"
}, - "flare_tag": {
- "name": "discuss",
- "bg_color_hex": "#000000",
- "text_color_hex": "#ffffff"
}
}
]
User's 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.
Authorizations:
query Parameters
page | integer <int32> >= 1 Default: 1 Pagination page |
per_page | integer <int32> [ 1 .. 1000 ] Default: 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. |
Responses
Response samples
- 200
- 401
[ ]
User's published 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.
Authorizations:
query Parameters
page | integer <int32> >= 1 Default: 1 Pagination page |
per_page | integer <int32> [ 1 .. 1000 ] Default: 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. |
Responses
Response samples
- 200
- 401
[ ]
User's unpublished 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.
Authorizations:
query Parameters
page | integer <int32> >= 1 Default: 1 Pagination page |
per_page | integer <int32> [ 1 .. 1000 ] Default: 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. |
Responses
Response samples
- 200
- 401
[ ]
User's all 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.
Authorizations:
query Parameters
page | integer <int32> >= 1 Default: 1 Pagination page |
per_page | integer <int32> [ 1 .. 1000 ] Default: 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. |
Responses
Response samples
- 200
- 401
[ ]
Unpublish an article
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.
Authorizations:
path Parameters
id required | integer <int32> >= 1 Example: 1 The ID of the article to unpublish. |
query Parameters
note | string Example: note=Admin requested unpublishing all articles via API Content for the note that's created along with unpublishing |
Responses
Response samples
- 401
- 404
{- "error": "unauthorized",
- "status": 401
}
display ads
This endpoint allows the client to create a new display ad.
Authorizations:
Request Body schema: application/json
name required | string For internal use, helps distinguish ads from one another |
body_markdown required | string The text (in markdown) of the ad (required) |
approved | boolean Ad must be both published and approved to be in rotation |
published | boolean Ad must be both published and approved to be in rotation |
organization_id | integer Identifies the organization to which the ad belongs |
display_to | string Default: "all" Enum: "all" "logged_in" "logged_out" Potentially limits visitors to whom the ad is visible |
placement_area required | string Enum: "sidebar_left" "sidebar_left_2" "sidebar_right" "post_sidebar" "post_comments" Identifies which area of site layout the ad can appear in |
tag_list | string Tags on which this ad can be displayed (blank is all/any tags) |
Responses
Request samples
- Payload
{- "name": "string",
- "body_markdown": "string",
- "approved": true,
- "published": true,
- "organization_id": 0,
- "display_to": "all",
- "placement_area": "sidebar_left",
- "tag_list": "string"
}
Response samples
- 200
- 401
- 422
{- "id": 91,
- "approved": true,
- "body_markdown": "# Hi, this is ad\nYep, it's an ad",
- "cached_tag_list": "",
- "clicks_count": 0,
- "created_at": "2023-01-12T00:00:23.787+08:00",
- "display_to": "all",
- "impressions_count": 0,
- "name": "Example Ad",
- "organization_id": null,
- "placement_area": "post_comments",
- "processed_html": "<h1> <a href=\"#hi-this-is-ad\" class=\"anchor\"> </a> Hi, this is ad</h1><p>Yep, it's an ad</p>",
- "published": true,
- "success_rate": 0,
- "type_of": "in_house",
- "updated_at": "2023-01-12T00:00:23.787+08:00",
- "tag_list": ""
}
display ad
This endpoint allows the client to retrieve a single display ad, via its id.
Authorizations:
path Parameters
id required | integer <int32> >= 1 Example: 123 The ID of the user to unpublish. |
Responses
Response samples
- 200
- 401
- 404
{- "id": 92,
- "approved": false,
- "body_markdown": "Hello _hey_ Hey hey 9",
- "cached_tag_list": "",
- "clicks_count": 0,
- "created_at": "2023-01-12T00:00:23.944+08:00",
- "display_to": "all",
- "impressions_count": 0,
- "name": "Display Ad 92",
- "organization_id": 667,
- "placement_area": "sidebar_left",
- "processed_html": "<p>Hello <em>hey</em> Hey hey 9</p>",
- "published": false,
- "success_rate": 0,
- "type_of": "in_house",
- "updated_at": "2023-01-12T00:00:23.947+08:00",
- "tag_list": ""
}
display ads
This endpoint allows the client to update the attributes of a single display ad, via its id.
Authorizations:
path Parameters
id required | integer <int32> >= 1 Example: 123 The ID of the user to unpublish. |
Request Body schema: application/json
name required | string For internal use, helps distinguish ads from one another |
body_markdown required | string The text (in markdown) of the ad (required) |
approved | boolean Ad must be both published and approved to be in rotation |
published | boolean Ad must be both published and approved to be in rotation |
organization_id | integer Identifies the organization to which the ad belongs |
display_to | string Default: "all" Enum: "all" "logged_in" "logged_out" Potentially limits visitors to whom the ad is visible |
placement_area required | string Enum: "sidebar_left" "sidebar_left_2" "sidebar_right" "post_sidebar" "post_comments" Identifies which area of site layout the ad can appear in |
tag_list | string Tags on which this ad can be displayed (blank is all/any tags) |
Responses
Request samples
- Payload
{- "name": "string",
- "body_markdown": "string",
- "approved": true,
- "published": true,
- "organization_id": 0,
- "display_to": "all",
- "placement_area": "sidebar_left",
- "tag_list": "string"
}
Response samples
- 200
- 401
- 404
{- "approved": false,
- "body_markdown": "Hello _hey_ Hey hey 10",
- "display_to": "all",
- "name": "Display Ad 93",
- "organization_id": 668,
- "placement_area": "sidebar_left",
- "published": false,
- "processed_html": "<p>Hello <em>hey</em> Hey hey 10</p>",
- "cached_tag_list": "",
- "id": 93,
- "clicks_count": 0,
- "created_at": "2023-01-12T00:00:24.163+08:00",
- "impressions_count": 0,
- "success_rate": 0,
- "type_of": "in_house",
- "updated_at": "2023-01-12T00:00:24.165+08:00",
- "tag_list": ""
}
unpublish
This endpoint allows the client to remove a display ad from rotation by un-publishing it.
Authorizations:
path Parameters
id required | integer <int32> >= 1 Example: 123 The ID of the user to unpublish. |
Responses
Response samples
- 401
- 404
{- "error": "unauthorized",
- "status": 401
}
Podcast Episodes
This endpoint allows the client to retrieve a list of podcast episodes. "Podcast episodes" are episodes belonging to podcasts. It will only return active (reachable) podcast episodes that belong to published podcasts available on the platform, ordered by descending publication date. It supports pagination, each page will contain 30 articles by default.
query Parameters
page | integer <int32> >= 1 Default: 1 Pagination page |
per_page | integer <int32> [ 1 .. 1000 ] Default: 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 | string Example: username=codenewbie Using this parameter will retrieve episodes belonging to a specific podcast. |
Responses
Response samples
- 200
- 404
[- {
- "type_of": "podcast_episodes",
- "class_name": "PodcastEpisode",
- "id": 115,
- "path": "/codenewbie/slug-4",
- "title": "2",
- "image_url": "/uploads/podcast/image/90/d7d60853-1d17-46c7-b5b2-a8ec981e0360.jpeg",
- "podcast": {
- "title": "Sapporo Premium",
- "slug": "codenewbie",
- "image_url": "/uploads/podcast/image/90/d7d60853-1d17-46c7-b5b2-a8ec981e0360.jpeg"
}
}
]
A Users or organizations profile image
This endpoint allows the client to retrieve a user or organization profile image information by its corresponding username.
Authorizations:
path Parameters
username required | string Example: janedoe The parameter is the username of the user or the username of the organization. |
Responses
Response samples
- 200
- 404
{- "type_of": "profile_image",
- "image_of": "user",
- "profile_image": "/uploads/user/profile_image/3647/b862b06c-e357-491a-b0ee-94f9ebe30557.jpeg",
- "profile_image_90": "/uploads/user/profile_image/3647/b862b06c-e357-491a-b0ee-94f9ebe30557.jpeg"
}
toggle reaction
This endpoint allows the client to toggle the user's reaction to a specified reactable (eg, Article, Comment, or User). For examples: * "Like"ing an Article will create a new "like" Reaction from the user for that Articles * "Like"ing that Article a second time will remove the "like" from the user
Authorizations:
query Parameters
category required | string Enum: "like" "readinglist" "unicorn" |
reactable_id required | integer <int32> |
reactable_type required | string Enum: "Comment" "Article" "User" |
Responses
Response samples
- 200
- 401
{- "result": "create",
- "category": "like",
- "id": 72,
- "reactable_id": 1548,
- "reactable_type": "Article"
}
create reaction
This endpoint allows the client to create a reaction to a specified reactable (eg, Article, Comment, or User). For examples: * "Like"ing an Article will create a new "like" Reaction from the user for that Articles * "Like"ing that Article a second time will return the previous "like"
Authorizations:
query Parameters
category required | string Enum: "like" "readinglist" "unicorn" |
reactable_id required | integer <int32> |
reactable_type required | string Enum: "Comment" "Article" "User" |
Responses
Response samples
- 200
- 401
{- "result": "none",
- "category": "like",
- "id": 74,
- "reactable_id": 1550,
- "reactable_type": "Article"
}
Readinglist
This endpoint allows the client to retrieve a list of articles that were saved to a Users readinglist.
It supports pagination, each page will contain 30
articles by default
Authorizations:
query Parameters
page | integer <int32> >= 1 Default: 1 Pagination page |
per_page | integer <int32> [ 1 .. 1000 ] Default: 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. |
Responses
Response samples
- 200
- 401
[ ]
A User
This endpoint allows the client to retrieve a single user, either by id or by the user's username.
For complete documentation, see the v0 API docs: https://developers.forem.com/api/v0#tag/users/operation/getUser
Authorizations:
path Parameters
id required | string |
Responses
Unpublish a User's Articles and Comments
This endpoint allows the client to unpublish all of the articles and comments created by a user.
The user associated with the API key must have any 'admin' or 'moderator' role.
This specified user's articles and comments will be unpublished and will no longer be visible to the public. They will remain in the database and will set back to draft status on the specified user's dashboard. Any notifications associated with the specified user's articles and comments will be deleted.
Note this endpoint unpublishes articles and comments asychronously: it will return a 204 NO CONTENT status code immediately, but the articles and comments will not be unpublished until the request is completed on the server.
Authorizations:
path Parameters
id required | integer <int32> >= 1 Example: 1 The ID of the user to unpublish. |
Responses
Response samples
- 401
- 404
{- "error": "unauthorized",
- "status": 401
}
Suspend a User
This endpoint allows the client to suspend a user.
The user associated with the API key must have any 'admin' or 'moderator' role.
This specified user will be assigned the 'suspended' role. Suspending a user will stop the user from posting new posts and comments. It doesn't delete any of the user's content, just prevents them from creating new content while suspended. Users are not notified of their suspension in the UI, so if you want them to know about this, you must notify them.
Authorizations:
path Parameters
id required | integer <int32> >= 1 Example: 1 The ID of the user to suspend. |
Responses
Response samples
- 401
- 404
{- "error": "unauthorized",
- "status": 401
}