Skip to main content
Documentation Powered by Redocly

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)

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
[
  • {
    }
]

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.

Responses

Response samples

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

reactions

create 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" "thinking" "hands"
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": 955,
  • "reactable_id": 4457,
  • "reactable_type": "Article"
}

users

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
}