Class: Forem::Article

Inherits:
APIResource show all
Extended by:
Forem::APIOperations::Create, Forem::APIOperations::List, Forem::APIOperations::Retrieve, Forem::APIOperations::Update
Includes:
Forem::APIOperations::Save
Defined in:
lib/forem/resources/article.rb

Overview

Represents a Forem article (blog post).

Articles are the core content type on Forem. They support full CRUD operations plus several custom endpoints for filtering by auth state, latest publication order, and full-text search.

Available operations (via mixins):

- +List+   — GET /api/articles
- +Create+ — POST /api/articles
- +Retrieve+ — GET /api/articles/:id
- +Update+ — PUT /api/articles/:id
- +Save+   — instance-level save (create or update)

List Parameters

When calling Article.list, the following query parameters are supported:

  • tag (String) — Filter by tag; can combine with top
  • tags (String) — Comma-separated tags; returns articles with ANY of these
  • tags_exclude (String) — Comma-separated tags to exclude
  • username (String) — Filter by user or organization username
  • state (String) — One of: "fresh", "rising", "all". Note: state=all only works combined with username and returns up to 1000 items
  • top (Integer) — Most popular articles in the last N days; can combine with tag
  • collection_id (Integer) — Articles in a specific collection, ordered by publication date
  • page (Integer) — Page number (default: 1)
  • per_page (Integer) — Items per page (default: 30, max: 1000)

Create Parameters

When calling Article.create, wrap all fields under the :article key:

Article Fields

Additional response attributes include ai_disclosure_level, ai_disclosure_label, cover_image, social_image, reading_time, positive_reactions_count, etc. articles = client.articles.list(per_page: 10, tag: "ruby") articles.data.each { |a| puts a.title }

Examples:

Create a new article

article = client.articles.create(
  article: { title: "Hello World", body_markdown: "# Hello", published: false }
)

Retrieve a single article by ID

article = client.articles.retrieve(12345)
puts article.title

See Also:

Constant Summary collapse

OBJECT_NAME = 
"article"
RESOURCE_PATH = 
"/api/articles"

Instance Attribute Summary

Attributes inherited from ForemObject

#requestor

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Forem::APIOperations::Create

create

Methods included from Forem::APIOperations::List

list

Methods included from Forem::APIOperations::Retrieve

retrieve

Methods included from Forem::APIOperations::Update

update

Methods included from Forem::APIOperations::Save

#save

Methods inherited from APIResource

#refresh, resource_path, #resource_url

Methods inherited from ForemObject

#==, #[], #[]=, construct_from, cursor_list, #initialize, #inspect, #method_missing, paginated_list, #respond_to_missing?, #to_hash

Methods included from Forem::APIOperations::Request

included, #request

Constructor Details

This class inherits a constructor from Forem::ForemObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Forem::ForemObject

Class Method Details

.latest(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::Article>

Return the most recently published articles ordered by publication date.

Sends a GET request to /api/articles/latest.

Examples:

latest = client.articles.latest(per_page: 5)
latest.each { |a| puts "#{a.published_at}: #{a.title}" }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 30)

Returns:

See Also:



192
193
194
 
# File 'lib/forem/resources/article.rb', line 192

def self.latest(params = {}, opts = {})
  paginated_list("/api/articles/latest", params, opts)
end

.me(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::Article>

Return articles authored by the authenticated user (all statuses).

Requires authentication. Returns articles in reverse chronological order, 30 per page.

Sends a GET request to /api/articles/me.

Examples:

my_articles = client.articles.me(per_page: 5)
my_articles.each { |a| puts "#{a.id}: #{a.title}" }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 30)

Returns:

See Also:



111
112
113
 
# File 'lib/forem/resources/article.rb', line 111

def self.me(params = {}, opts = {})
  paginated_list("/api/articles/me", params, opts)
end

.me_all(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::Article>

Return all articles authored by the authenticated user regardless of status.

Requires authentication. Returns articles in reverse chronological order, 30 per page.

Sends a GET request to /api/articles/me/all.

Examples:

all = client.articles.me_all
all.auto_paging_each { |a| puts a.title }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 30)

Returns:

See Also:



174
175
176
 
# File 'lib/forem/resources/article.rb', line 174

def self.me_all(params = {}, opts = {})
  paginated_list("/api/articles/me/all", params, opts)
end

.me_published(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::Article>

Return published articles authored by the authenticated user.

Requires authentication. Returns articles in reverse chronological order, 30 per page.

Sends a GET request to /api/articles/me/published.

Examples:

published = client.articles.me_published(per_page: 20)
published.each { |a| puts a.title }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 30)

Returns:

See Also:



132
133
134
 
# File 'lib/forem/resources/article.rb', line 132

def self.me_published(params = {}, opts = {})
  paginated_list("/api/articles/me/published", params, opts)
end

.me_unpublished(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::Article>

Return unpublished (draft) articles authored by the authenticated user.

Requires authentication. Returns articles in reverse chronological order, 30 per page.

Sends a GET request to /api/articles/me/unpublished.

Examples:

drafts = client.articles.me_unpublished
drafts.each { |a| puts "Draft: #{a.title}" }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 30)

Returns:

See Also:



153
154
155
 
# File 'lib/forem/resources/article.rb', line 153

def self.me_unpublished(params = {}, opts = {})
  paginated_list("/api/articles/me/unpublished", params, opts)
end

.retrieve_by_path(username, slug, opts = {}) ⇒ Forem::Article

Retrieve a single article by the author's username and the article's slug.

Sends a GET request to /api/articles/:username/:slug.

Examples:

article = client.articles.retrieve_by_path("ben", "my-first-post")
puts article.title

Parameters:

  • username (String) —

    the author's Forem username

  • slug (String) —

    the article slug (the URL-friendly title segment)

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Returns:

See Also:



254
255
256
257
258
 
# File 'lib/forem/resources/article.rb', line 254

def self.retrieve_by_path(username, slug, opts = {})
  requestor = opts[:requestor]
  resp = request(:get, "/api/articles/#{CGI.escape(username)}/#{CGI.escape(slug)}", {}, opts)
  construct_from(resp.parsed_body, requestor: requestor)
end

.search(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::Article>

Search published articles by keyword.

Sends a GET request to /api/articles/search.

Examples:

results = client.articles.search(q: "ruby on rails")
results.each { |a| puts a.title }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :q (String) —

    search query string

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 30)

Returns:

See Also:



211
212
213
 
# File 'lib/forem/resources/article.rb', line 211

def self.search(params = {}, opts = {})
  paginated_list("/api/articles/search", params, opts)
end

.semantic_search(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::Article>

Semantically search published articles using Forem's embeddings-based search.

Unlike search (keyword matching), this endpoint finds articles whose meaning is close to the query text, using vector similarity. Requires authentication.

Sends a GET request to /api/articles/semantic_search.

Examples:

results = client.articles.semantic_search(q: "how to deploy rails apps")
results.each { |a| puts "#{a.title} (#{a.similarity})" }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :q (String) —

    the search query text (required)

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 10, max: 50)

  • :threshold (Float) —

    optional cosine distance threshold (0.0-2.0) used to filter out weakly-related results

Returns:

  • (Forem::ListObject<Forem::Article>) —

    paginated list of articles matching the query, ordered by relevance. Each article additionally exposes distance (cosine distance) and similarity (1 - distance) attributes.

See Also:



238
239
240
 
# File 'lib/forem/resources/article.rb', line 238

def self.semantic_search(params = {}, opts = {})
  paginated_list("/api/articles/semantic_search", params, opts)
end

Instance Method Details

#unpublish(opts = {}) ⇒ ForemResponse

Unpublish this article, reverting it to draft status.

Marks the article as draft. Keeps content, deletes notifications, preserves comments. Requires admin or moderator role.

Sends a PUT request to /api/articles/:id/unpublish.

Examples:

article = client.articles.retrieve(42)
article.unpublish

Parameters:

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Returns:

See Also:



90
91
92
 
# File 'lib/forem/resources/article.rb', line 90

def unpublish(opts = {})
  request(:put, "#{resource_url}/unpublish", {}, opts)
end