---
title: "Published articles"
method: GET
path: "/api/articles"
tags: ["articles"]
---

# Published articles

`GET /api/articles`

This endpoint allows the client to retrieve a list of articles.

"Articles" are all the posts that users create on DEV/Forem that typically show up in the feed. They can be a blog post, a discussion question, a help thread etc. but are referred to as articles 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 Parameter Usage Tips:
- **Filtering by Tags**:
  - Use `tag` to filter articles containing a single exact tag (e.g. `tag=discuss`).
  - Use `tags` to retrieve articles containing *any* of the comma-separated list of tags (e.g. `tags=javascript,css`).
  - Use `tags_exclude` to filter out articles containing any of the comma-separated list of tags (e.g. `tags_exclude=node,java`).
- **Filtering by User / Organization**:
  - Use `username` to retrieve articles belonging to a specific User or Organization. Articles are returned in reverse chronological publication order.
- **State Options**:
  - Use `state=fresh` to fetch fresh articles.
  - Use `state=rising` to fetch rising/trending articles.
  - Combine `state=all` with `username` to fetch up to `1000` articles (both published and unpublished) from that user/organization in a single page.
- **Top / Popularity**:
  - Use `top=N` to return the most popular articles published in the last `N` days (e.g. `top=7` for top articles of the week, `top=30` for top of the month). This parameter can be combined with `tag` to find top articles in a specific niche.
- **Collections**:
  - Use `collection_id` to retrieve articles belonging to a specific collection/series, sorted chronologically.

## Query parameters

- `page` integer
- `per_page` integer
- `tag` string
- `tags` string
- `tags_exclude` string
- `username` string
- `state` 'fresh' | 'rising' | 'all'
- `top` integer
- `collection_id` integer

## Response `200`

A List of Articles

- ArticleIndex[]
  - `type_of` string, required
  - `id` integer, required
  - `title` string, required
  - `description` string, required
  - `cover_image` string, url, nullable, required
  - `readable_publish_date` string, required
  - `social_image` string, url, required
  - `tag_list` string[], required
  - `tags` string, required
  - `slug` string, required
  - `path` string, path, required
  - `url` string, url, required
  - `canonical_url` string, url, required
  - `positive_reactions_count` integer, required
  - `public_reactions_count` integer, required
  - `created_at` string, date-time, required
  - `edited_at` string, date-time, nullable, required
  - `crossposted_at` string, date-time, nullable, required
  - `published_at` string, date-time, required
  - `last_comment_at` string, date-time, required
  - `published_timestamp` string, date-time, required — Crossposting or published date time
  - `reading_time_minutes` integer, required — Reading time, in minutes
  - `ai_disclosure_level` 'not_disclosed' | 'no_ai' | 'some_ai' | 'fully_autonomous' — Level of AI tooling usage disclosure
  - `ai_disclosure_label` string — Human-readable label of AI disclosure
  - `user` SharedUser, required — The resource creator
    - `name` string
    - `username` string
    - `twitter_username` string, nullable
    - `github_username` string, nullable
    - `website_url` string, url, nullable
    - `profile_image` string — Profile image (640x640)
    - `profile_image_90` string — Profile image (90x90)
  - `flare_tag` ArticleFlareTag — Flare tag of the article
    - `name` string
    - `bg_color_hex` string, nullable — Background color (hexadecimal)
    - `text_color_hex` string, nullable — Text color (hexadecimal)
  - `organization` SharedOrganization — The organization the resource belongs to
    - `name` string
    - `username` string
    - `slug` string
    - `profile_image` string, url — Profile image (640x640)
    - `profile_image_90` string, url — Profile image (90x90)

## Changes

- **2026-08-17** (v1) `32364ddfcc63` — 2 info
  - added the optional property `items/ai_disclosure_label` to the response with the `200` status
  - added the optional property `items/ai_disclosure_level` to the response with the `200` status
- **2023-02-03** (v1) `0789a6ed97e3` — 2 breaking
  - the response property `items/flare_tag/bg_color_hex` became nullable for the status `200`
  - the response property `items/flare_tag/text_color_hex` became nullable for the status `200`

[Change history](https://skmtc.dev/forem/apis/forem-api-v1/changes/api/articles/get.md)

---

[API](https://skmtc.dev/forem/apis/forem-api-v1.md) · [All operations](https://skmtc.dev/forem/apis/forem-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/forem/forem-api-v1/revisions/1f64f71fc2a7/schema)