Skip to main content
API docs 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

Publish article

This endpoint allows the client to create a new article.

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

Authorizations:
api-key
Request Body schema: application/json
object
title
string
body_markdown
string
published
boolean
Default: false
series
string or null
main_image
string or null
canonical_url
string or null
description
string
tags
string
organization_id
integer or null

Responses

Request samples

Content type
application/json
{
  • "article": {
    }
}

Response samples

Content type
application/json
{
  • "type_of": "article",
  • "id": 251,
  • "title": "New article",
  • "description": "New post example",
  • "readable_publish_date": "Apr 14",
  • "slug": "new-article-4aca",
  • "path": "/username383/new-article-4aca",
  • "url": "http://localhost:3000/username383/new-article-4aca",
  • "comments_count": 0,
  • "public_reactions_count": 0,
  • "collection_id": 11,
  • "published_timestamp": "2023-04-14T14:45:32Z",
  • "positive_reactions_count": 0,
  • "cover_image": "https://thepracticaldev.s3.amazonaws.com/i/5wfo25724gzgk5e5j50g.jpg",
  • "social_image": "https://thepracticaldev.s3.amazonaws.com/i/5wfo25724gzgk5e5j50g.jpg",
  • "canonical_url": "https://dev.to/fdocr/headless-chrome-dual-mode-tests-for-ruby-on-rails-4p6g",
  • "created_at": "2023-04-14T14:45:32Z",
  • "edited_at": null,
  • "crossposted_at": null,
  • "published_at": "2023-04-14T14:45:32Z",
  • "last_comment_at": "2023-04-14T14:45:32Z",
  • "reading_time_minutes": 1,
  • "tag_list": "",
  • "tags": [ ],
  • "body_html": "<p><strong>New</strong> body for the article</p>\n\n",
  • "body_markdown": "**New** body for the article",
  • "user": {
    }
}

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

Published articles sorted by published date

This endpoint allows the client to retrieve a list of articles. ordered by descending publish 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.

Responses

Response samples

Content type
application/json
[]

Published article by id

This endpoint allows the client to retrieve a single published article given its id.

path Parameters
id
required
integer

Responses

Response samples

Content type
application/json
{
  • "type_of": "article",
  • "id": 258,
  • "title": "Pale Kings and Princes179",
  • "description": "Etsy you probably haven't heard of them carry humblebrag 90's try-hard. Distillery asymmetrical...",
  • "readable_publish_date": "Apr 14",
  • "slug": "pale-kings-and-princes179-381c",
  • "path": "/username391/pale-kings-and-princes179-381c",
  • "url": "http://localhost:3000/username391/pale-kings-and-princes179-381c",
  • "comments_count": 0,
  • "public_reactions_count": 0,
  • "collection_id": null,
  • "published_timestamp": "2023-04-14T14:45:32Z",
  • "positive_reactions_count": 0,
  • "cover_image": "http://localhost:3000/assets/19-ed58d3e8defcefc445020631589697a05e725243e834b5192aee4e6b91a3e927.png",
  • "social_image": "http://localhost:3000/assets/19-ed58d3e8defcefc445020631589697a05e725243e834b5192aee4e6b91a3e927.png",
  • "canonical_url": "http://localhost:3000/username391/pale-kings-and-princes179-381c",
  • "created_at": "2023-04-14T14:45:32Z",
  • "edited_at": null,
  • "crossposted_at": null,
  • "published_at": "2023-04-14T14:45:32Z",
  • "last_comment_at": "2023-04-14T14:45:32Z",
  • "reading_time_minutes": 1,
  • "tag_list": "discuss",
  • "tags": [
    ],
  • "body_html": "<p>Etsy you probably haven't heard of them carry humblebrag 90's try-hard. Distillery asymmetrical godard trust fund quinoa pug paleo. Letterpress green juice plaid.</p>\n\n<p>Organic +1 pour-over banh mi disrupt listicle. Cronut offal flexitarian twee health poutine cred. Hashtag godard church-key etsy put a bird on it.</p>\n\n",
  • "body_markdown": "---\ntitle: Pale Kings and Princes179\npublished: true\ntags: discuss\ndate: \nseries: \ncanonical_url: \n\n---\n\nEtsy you probably haven't heard of them carry humblebrag 90's try-hard. Distillery asymmetrical godard trust fund quinoa pug paleo. Letterpress green juice plaid.\n\n\nOrganic +1 pour-over banh mi disrupt listicle. Cronut offal flexitarian twee health poutine cred. Hashtag godard church-key etsy put a bird on it.\n\n",
  • "user": {
    },
  • "flare_tag": {
    }
}

Update an article by id

This endpoint allows the client to update an existing article.

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

Authorizations:
api-key
path Parameters
id
required
integer <int32> >= 1
Example: 123

The ID of the user to unpublish.

Request Body schema: application/json
object
title
string
body_markdown
string
published
boolean
Default: false
series
string or null
main_image
string or null
canonical_url
string or null
description
string
tags
string
organization_id
integer or null

Responses

Request samples

Content type
application/json
{
  • "article": {
    }
}

Response samples

Content type
application/json
{}

Published article by path

This endpoint allows the client to retrieve a single published article given its path.

path Parameters
username
required
string
slug
required
string

Responses

Response samples

Content type
application/json
{
  • "type_of": "article",
  • "id": 262,
  • "title": "Noli Me Tangere183",
  • "description": "Normcore williamsburg try-hard artisan. Vinyl park shoreditch gastropub vegan knausgaard. Ethical...",
  • "readable_publish_date": "Apr 14",
  • "slug": "noli-me-tangere183-1lj5",
  • "path": "/username396/noli-me-tangere183-1lj5",
  • "url": "http://localhost:3000/username396/noli-me-tangere183-1lj5",
  • "comments_count": 0,
  • "public_reactions_count": 0,
  • "collection_id": null,
  • "published_timestamp": "2023-04-14T14:45:33Z",
  • "positive_reactions_count": 0,
  • "cover_image": "http://localhost:3000/assets/37-94b286825ffd9f2b47c9842cf4f262b7c89e789797eba40196bc14b5c2359e75.png",
  • "social_image": "http://localhost:3000/assets/37-94b286825ffd9f2b47c9842cf4f262b7c89e789797eba40196bc14b5c2359e75.png",
  • "canonical_url": "http://localhost:3000/username396/noli-me-tangere183-1lj5",
  • "created_at": "2023-04-14T14:45:33Z",
  • "edited_at": null,
  • "crossposted_at": null,
  • "published_at": "2023-04-14T14:45:33Z",
  • "last_comment_at": "2023-04-14T14:45:33Z",
  • "reading_time_minutes": 1,
  • "tag_list": "discuss",
  • "tags": [
    ],
  • "body_html": "<p>Normcore williamsburg try-hard artisan. Vinyl park shoreditch gastropub vegan knausgaard.</p>\n\n<p>Ethical trust fund intelligentsia pbr&amp;b. Brunch seitan pug waistcoat farm-to-table flexitarian health. Tumblr banh mi goth retro diy.</p>\n\n",
  • "body_markdown": "---\ntitle: Noli Me Tangere183\npublished: true\ntags: discuss\ndate: \nseries: \ncanonical_url: \n\n---\n\nNormcore williamsburg try-hard artisan. Vinyl park shoreditch gastropub vegan knausgaard.\n\n\nEthical trust fund intelligentsia pbr&b. Brunch seitan pug waistcoat farm-to-table flexitarian health. Tumblr banh mi goth retro diy.\n\n",
  • "user": {
    },
  • "flare_tag": {
    }
}

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
}

Organization's Articles

This endpoint allows the client to retrieve a list of Articles belonging to the organization

It supports pagination, each page will contain 30 users by default.

path Parameters
username
required
string
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
[
  • {
    }
]

Articles with a video

This endpoint allows the client to retrieve a list of articles that are uploaded with a video.

It will only return published video articles ordered by descending popularity.

It supports pagination, each page will contain 24 articles by default.

query Parameters
page
integer <int32> >= 1
Default: 1

Pagination page

per_page
integer <int32> [ 1 .. 1000 ]
Default: 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.

Responses

Response samples

Content type
application/json
[]

users

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

Organization's users

This endpoint allows the client to retrieve a list of users belonging to the organization

It supports pagination, each page will contain 30 users by default.

path Parameters
username
required
string
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
[
  • {
    },
  • {
    }
]

The authenticated user

This endpoint allows the client to retrieve information about the authenticated user

Authorizations:
api-key

Responses

Response samples

Content type
application/json
{
  • "type_of": "user",
  • "id": 1431,
  • "username": "username480",
  • "name": "Willy \"Myron\" \\:/ Herzog",
  • "twitter_username": "twitter480",
  • "github_username": "github480",
  • "summary": null,
  • "location": null,
  • "website_url": null,
  • "joined_at": "Apr 14, 2023",
  • "profile_image": "/uploads/user/profile_image/1431/b547e3a6-5076-44dd-a4f6-9b85022b4e76.jpeg"
}

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

Response samples

Content type
application/json
{ }

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
}

Invite a User

This endpoint allows the client to trigger an invitation to the provided email address.

    It requires a token from a user with `super_admin` privileges.
Authorizations:
api-key
Request Body schema: application/json
email
string
name
string or null

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "name": "string"
}

Response samples

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

comments

Comments

This endpoint allows the client to retrieve all comments belonging to an article or podcast episode as threaded conversations.

It will return the all top level comments with their nested comments as threads. See the format specification for further details.

query Parameters
a_id
string
Example: a_id=321

Article identifier.

p_id
string
Example: p_id=321

Podcast Episode identifier.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Comment by id

This endpoint allows the client to retrieve a comment as well as his descendants comments.

It will return the required comment (the root) with its nested descendants as a thread.

See the format specification for further details.

path Parameters
id
required
integer
Example: 321

Comment identifier.

Responses

Response samples

Content type
application/json
{
  • "type_of": "comment",
  • "id_code": "54",
  • "created_at": "2023-04-14T14:45:35Z",
  • "body_html": "<p>Ramps tacos jean shorts humblebrag street bicycle rights paleo. Actually green juice chartreuse tattooed cliche. 8-bit bushwick diy aesthetic.</p>\n\n",
  • "user": {
    },
  • "children": [ ]
}

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
[$ref]
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "id": 193,
  • "approved": true,
  • "body_markdown": "# Hi, this is ad\nYep, it's an ad",
  • "cached_tag_list": "",
  • "clicks_count": 0,
  • "created_at": "2023-04-14T18:45:35.606+04:00",
  • "creator_id": null,
  • "display_to": "all",
  • "exclude_article_ids": "",
  • "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-04-14T18:45:35.606+04:00",
  • "audience_segment_type": null,
  • "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 display ad.

Responses

Response samples

Content type
application/json
{
  • "id": 196,
  • "approved": false,
  • "body_markdown": "Hello _hey_ Hey hey 9",
  • "cached_tag_list": "",
  • "clicks_count": 0,
  • "created_at": "2023-04-14T18:45:35.813+04:00",
  • "creator_id": null,
  • "display_to": "all",
  • "exclude_article_ids": "",
  • "impressions_count": 0,
  • "name": "Display Ad 196",
  • "organization_id": 304,
  • "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-04-14T18:45:35.817+04:00",
  • "audience_segment_type": null,
  • "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 display ad.

Request Body schema: application/json
[$ref]
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "approved": false,
  • "body_markdown": "Hello _hey_ Hey hey 10",
  • "creator_id": null,
  • "display_to": "all",
  • "name": "Display Ad 198",
  • "organization_id": 306,
  • "placement_area": "sidebar_left",
  • "published": false,
  • "type_of": "in_house",
  • "exclude_article_ids": "",
  • "cached_tag_list": "",
  • "id": 198,
  • "clicks_count": 0,
  • "created_at": "2023-04-14T18:45:36.047+04:00",
  • "impressions_count": 0,
  • "processed_html": "<p>Hello <em>hey</em> Hey hey 10</p>",
  • "success_rate": 0,
  • "updated_at": "2023-04-14T18:45:36.051+04:00",
  • "audience_segment_type": null,
  • "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 display ad to unpublish.

Responses

Response samples

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

followed_tags

Followed Tags

This endpoint allows the client to retrieve a list of the tags they follow.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

tags

Followed Tags

This endpoint allows the client to retrieve a list of the tags they follow.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Tags

This endpoint allows the client to retrieve a list of tags that can be used to tag articles.

It will return tags ordered by popularity.

It supports pagination, each page will contain 10 tags by default.

query Parameters
page
integer <int32> >= 1
Default: 1

Pagination page

per_page
integer <int32> [ 1 .. 1000 ]
Default: 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.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

followers

Followers

This endpoint allows the client to retrieve a list of the followers they have. "Followers" are users that are following other users on the website. It supports pagination, each page will contain 80 followers 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.

sort
string
Example: sort=created_at

Default is 'created_at'. Specifies the sort order for the created_at param of the follow relationship. To sort by newest followers first (descending order) specify ?sort=-created_at.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

organizations

An organization

This endpoint allows the client to retrieve a single organization by their username

path Parameters
username
required
string

Responses

Response samples

Content type
application/json
{
  • "type_of": "organization",
  • "id": 323,
  • "username": "org77",
  • "name": "Skiles-Frami",
  • "summary": "Franzen seitan mustache cred. Gluten-free flannel gastropub hoodie vinegar wolf mixtape.",
  • "twitter_username": "org26",
  • "github_username": "org5524",
  • "url": "http://jacobs.com/assunta.rau",
  • "location": null,
  • "tech_stack": null,
  • "tag_line": null,
  • "story": null,
  • "joined_at": "2023-04-14T14:45:37Z",
  • "profile_image": "/uploads/organization/profile_image/323/d1677329-759a-44e1-866e-c5be50e9593b.png"
}

Organization's users

This endpoint allows the client to retrieve a list of users belonging to the organization

It supports pagination, each page will contain 30 users by default.

path Parameters
username
required
string
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
[
  • {
    },
  • {
    }
]

Organization's Articles

This endpoint allows the client to retrieve a list of Articles belonging to the organization

It supports pagination, each page will contain 30 users by default.

path Parameters
username
required
string
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
[
  • {
    }
]

pages

show details for all pages

This endpoint allows the client to retrieve details for all Page objects.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

pages

This endpoint allows the client to create a new page.

Authorizations:
api-key
Request Body schema: application/json
title
string

Title of the page

slug
string

Used to link to this page in URLs, must be unique and URL-safe

description
string

For internal use, helps similar pages from one another

body_markdown
string

The text (in markdown) of the ad (required)

body_json
string

For JSON pages, the JSON body

is_top_level_path
boolean

If true, the page is available at '/{slug}' instead of '/page/{slug}', use with caution

template
string
Default: "contained"
Enum: "contained" "full_within_layout" "nav_bar_included" "json"

Controls what kind of layout the page is rendered in

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "slug": "string",
  • "description": "string",
  • "body_markdown": "string",
  • "body_json": "string",
  • "is_top_level_path": true,
  • "template": "contained"
}

Response samples

Content type
application/json
{
  • "id": 7,
  • "title": "Example Page",
  • "slug": "example1",
  • "description": "a new page",
  • "is_top_level_path": false,
  • "landing_page": false,
  • "body_html": null,
  • "body_json": null,
  • "body_markdown": "# Hi, this is a New Page\nYep, it's an a new page",
  • "processed_html": "<h1>\n <a name=\"hi-this-is-a-new-page\" href=\"#hi-this-is-a-new-page\">\n </a>\n Hi, this is a New Page\n</h1>\n\n<p>Yep, it's an a new page</p>\n\n",
  • "social_image": {
    },
  • "template": "contained"
}

show details for a page

This endpoint allows the client to retrieve details for a single Page object, specified by ID.

path Parameters
id
required
integer <int32> >= 1
Example: 1

The ID of the page.

Responses

Response samples

Content type
application/json
{
  • "id": 10,
  • "title": "A Swiftly Tilting Planet",
  • "slug": "corn-laser",
  • "description": "Inventore ad qui dolore.",
  • "is_top_level_path": false,
  • "landing_page": false,
  • "body_html": null,
  • "body_json": null,
  • "body_markdown": "In sit sit voluptas.",
  • "processed_html": "<p>In sit sit voluptas.</p>\n\n",
  • "social_image": {
    },
  • "template": "contained"
}

update details for a page

This endpoint allows the client to retrieve details for a single Page object, specified by ID.

Authorizations:
api-key
path Parameters
id
required
integer <int32> >= 1
Example: 1

The ID of the page.

Request Body schema: application/json
title
required
string

Title of the page

slug
required
string

Used to link to this page in URLs, must be unique and URL-safe

description
required
string

For internal use, helps similar pages from one another

body_markdown
string or null

The text (in markdown) of the ad (required)

body_json
string or null

For JSON pages, the JSON body

is_top_level_path
boolean

If true, the page is available at '/{slug}' instead of '/page/{slug}', use with caution

social_image
object or null
template
required
string
Default: "contained"
Enum: "contained" "full_within_layout" "nav_bar_included" "json"

Controls what kind of layout the page is rendered in

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "slug": "string",
  • "description": "string",
  • "body_markdown": "string",
  • "body_json": "string",
  • "is_top_level_path": true,
  • "social_image": { },
  • "template": "contained"
}

Response samples

Content type
application/json
{
  • "id": 11,
  • "title": "New Title",
  • "slug": "authority-figure",
  • "description": "Et odio nostrum dolorem.",
  • "is_top_level_path": false,
  • "landing_page": false,
  • "body_html": null,
  • "body_json": null,
  • "body_markdown": "Consequatur ex soluta libero.",
  • "processed_html": "<p>Consequatur ex soluta libero.</p>\n\n",
  • "social_image": {
    },
  • "template": "contained"
}

remove a page

This endpoint allows the client to delete a single Page object, specified by ID.

Authorizations:
api-key
path Parameters
id
required
integer <int32> >= 1
Example: 1

The ID of the page.

Responses

Response samples

Content type
application/json
{
  • "id": 14,
  • "title": "The Skull Beneath the Skin",
  • "slug": "appointment-provision",
  • "description": "Et error fuga natus.",
  • "is_top_level_path": false,
  • "landing_page": false,
  • "body_html": null,
  • "body_json": null,
  • "body_markdown": "Quo quibusdam nisi numquam.",
  • "processed_html": "<p>Quo quibusdam nisi numquam.</p>\n\n",
  • "social_image": {
    },
  • "template": "contained"
}

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/1419/f2b13e85-a3a0-49cf-9da0-7922248be024.jpeg",
  • "profile_image_90": "/uploads/user/profile_image/1419/f2b13e85-a3a0-49cf-9da0-7922248be024.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" "unicorn" "exploding_head" "raised_hands" "fire"
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": 13,
  • "reactable_id": 283,
  • "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" "unicorn" "exploding_head" "raised_hands" "fire"
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": 15,
  • "reactable_id": 285,
  • "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
[ ]

videos

Articles with a video

This endpoint allows the client to retrieve a list of articles that are uploaded with a video.

It will only return published video articles ordered by descending popularity.

It supports pagination, each page will contain 24 articles by default.

query Parameters
page
integer <int32> >= 1
Default: 1

Pagination page

per_page
integer <int32> [ 1 .. 1000 ]
Default: 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.

Responses

Response samples

Content type
application/json
[]