Skip to main content

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.

articles

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

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=all the number of items returned will be 1000 instead of the default 30. This parameter can be used in conjuction with state.

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 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
integer <int32> >= 1
Example: top=2

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

Content type
application/json
[
  • {
    }
]

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:
api-key
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

Content type
application/json
[ ]

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:
api-key
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

Content type
application/json
[ ]

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:
api-key
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

Content type
application/json
[ ]

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:
api-key
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

Content type
application/json
[ ]

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:
api-key
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

Content type
application/json
{
  • "error": "unauthorized",
  • "status": 401
}

display ads

display ads

This endpoint allows the client to retrieve a list of all display ads.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
[ ]

display ads

This endpoint allows the client to create a new display ad.

Authorizations:
api-key
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

Content type
application/json
{
  • "name": "string",
  • "body_markdown": "string",
  • "approved": true,
  • "published": true,
  • "organization_id": 0,
  • "display_to": "all",
  • "placement_area": "sidebar_left",
  • "tag_list": "string"
}

Response samples

Content type
application/json
{
  • "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:
api-key
path Parameters
id
required
integer <int32> >= 1
Example: 123

The ID of the user to unpublish.

Responses

Response samples

Content type
application/json
{
  • "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:
api-key
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

Content type
application/json
{
  • "name": "string",
  • "body_markdown": "string",
  • "approved": true,
  • "published": true,
  • "organization_id": 0,
  • "display_to": "all",
  • "placement_area": "sidebar_left",
  • "tag_list": "string"
}

Response samples

Content type
application/json
{
  • "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:
api-key
path Parameters
id
required
integer <int32> >= 1
Example: 123

The ID of the user to unpublish.

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "status": 401
}

podcast_episodes

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

Content type
application/json
[
  • {
    }
]

profile images

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:
api-key
path Parameters
username
required
string
Example: janedoe

The parameter is the username of the user or the username of the organization.

Responses

Response samples

Content type
application/json
{
  • "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"
}

reactions

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:
api-key
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

Content type
application/json
{
  • "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:
api-key
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

Content type
application/json
{
  • "result": "none",
  • "category": "like",
  • "id": 74,
  • "reactable_id": 1550,
  • "reactable_type": "Article"
}

readinglist

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:
api-key
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

Content type
application/json
[ ]

users

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:
api-key
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:
api-key
path Parameters
id
required
integer <int32> >= 1
Example: 1

The ID of the user to unpublish.

Responses

Response samples

Content type
application/json
{
  • "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:
api-key
path Parameters
id
required
integer <int32> >= 1
Example: 1

The ID of the user to suspend.

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "status": 401
}