# RealWorld API Article Response Structure: Complete JSON Format Guide

> Discover the RealWorld API article response structure. Learn how articles are returned in a JSON object, including the articles array and count, with detailed articleMapper transformations.

- Repository: [Thinkster/realworld](https://github.com/gothinkster/realworld)
- Tags: api-reference
- Published: 2026-02-28

---

**When querying article endpoints in the RealWorld API, the server returns a JSON object containing an `articles` array and an `articlesCount` integer, with each article transformed by the `articleMapper` function before serialization.**

The RealWorld API provides a standardized backend specification for testing frontend implementations. When building clients that consume article data from the `gothinkster/realworld` repository, understanding the exact **RealWorld API article response structure** ensures your components parse the JSON correctly across all list and feed endpoints.

## Top-Level Response Properties

Every article query endpoint returns a consistent wrapper object with two properties.

### The articles Array

The `articles` property contains an array of article objects matching your query criteria. According to the route handlers in [`apps/api/server/routes/api/articles/index.get.ts`](https://github.com/gothinkster/realworld/blob/main/apps/api/server/routes/api/articles/index.get.ts) and [`apps/api/server/routes/api/articles/feed.get.ts`](https://github.com/gothinkster/realworld/blob/main/apps/api/server/routes/api/articles/feed.get.ts), the system packages the transformed data as `{ articles, articlesCount }` before sending the response.

### The articlesCount Field

The `articlesCount` property is an integer representing the total number of articles satisfying the query parameters, ignoring pagination limits. This value enables frontend clients to calculate total pages for pagination controls.

## Article Object Schema

Each object inside the `articles` array follows the structure defined in [`apps/api/server/utils/article.mapper.ts`](https://github.com/gothinkster/realworld/blob/main/apps/api/server/utils/article.mapper.ts). The `articleMapper` utility converts raw database rows into the public API shape.

### Core Article Fields

- **slug**: URL-friendly identifier string (e.g., `"how-to-code-123"`)
- **title**: Article title string
- **description**: Short summary string
- **body**: Full content string (omitted from list endpoints via `omit: { body: true }`)
- **tagList**: Array of strings representing attached tags
- **createdAt**: ISO-8601 date string of creation timestamp
- **updatedAt**: ISO-8601 date string of last update timestamp

### Engagement and Author Data

- **favorited**: Boolean indicating if the requesting user has favorited the article (defaults to `false` for unauthenticated requests)
- **favoritesCount**: Integer count of total users who favorited the article
- **author**: Object containing `username`, `image`, and `followedBy` boolean properties (mapped via [`author.mapper.ts`](https://github.com/gothinkster/realworld/blob/main/author.mapper.ts))

## Source Code Implementation

The response structure is assembled in specific route handlers and utility functions within the repository.

### Route Handlers

In [`apps/api/server/routes/api/articles/index.get.ts`](https://github.com/gothinkster/realworld/blob/main/apps/api/server/routes/api/articles/index.get.ts), the global article list handler executes the query, retrieves both the paginated results and total count, and returns them as a structured object. The personalized feed endpoint in [`apps/api/server/routes/api/articles/feed.get.ts`](https://github.com/gothinkster/realworld/blob/main/apps/api/server/routes/api/articles/feed.get.ts) follows an identical pattern but filters by followed authors.

### Data Transformation

The `articleMapper` function in [`apps/api/server/utils/article.mapper.ts`](https://github.com/gothinkster/realworld/blob/main/apps/api/server/utils/article.mapper.ts) handles the transformation logic, ensuring consistent field naming and calculating the `favorited` status based on the requesting user's ID.

## Practical Query Examples

The following examples demonstrate how to request and handle the article response structure against the live RealWorld API.

### Fetching Global Articles with cURL

```bash
curl -s "https://api.realworld.io/api/articles?limit=5&offset=0" \
  -H "Accept: application/json"

```

**Expected Response:**

```json
{
  "articles": [
    {
      "slug": "how-to-code-123",
      "title": "How to code",
      "description": "A short guide",
      "tagList": ["programming", "tutorial"],
      "createdAt": "2024-09-01T12:34:56.789Z",
      "updatedAt": "2024-09-02T08:20:10.123Z",
      "favorited": false,
      "favoritesCount": 3,
      "author": {
        "username": "johndoe",
        "image": "https://api.realworld.io/images/johndoe.jpg",
        "followedBy": false
      }
    }
  ],
  "articlesCount": 42
}

```

### Consuming the API with JavaScript Fetch

```javascript
async function loadArticles(page = 1, limit = 10) {
  const offset = (page - 1) * limit;
  const res = await fetch(
    `https://api.realworld.io/api/articles?limit=${limit}&offset=${offset}`,
    { headers: { Accept: "application/json" } }
  );
  const { articles, articlesCount } = await res.json();

  console.log(`Total articles: ${articlesCount}`);
  return { articles, articlesCount };
}

```

### Authenticated Feed Request

When accessing the personalized feed at `GET /api/articles/feed`, include an authorization header. The response structure remains identical to the global list, but filters to articles by followed authors:

```bash
curl -s "https://api.realworld.io/api/articles/feed?limit=5" \
  -H "Authorization: Token <YOUR_JWT>"

```

## Summary

- The **RealWorld API article response structure** always includes `articles` (array) and `articlesCount` (integer) at the top level.
- Article objects contain metadata fields (`slug`, `title`, `description`), timestamps, tag arrays, and engagement metrics (`favorited`, `favoritesCount`).
- The `body` field is intentionally omitted from list endpoints to reduce payload size.
- The `articleMapper` utility in [`apps/api/server/utils/article.mapper.ts`](https://github.com/gothinkster/realworld/blob/main/apps/api/server/utils/article.mapper.ts) standardizes the transformation from database records to API responses.
- Route handlers in [`index.get.ts`](https://github.com/gothinkster/realworld/blob/main/index.get.ts) and [`feed.get.ts`](https://github.com/gothinkster/realworld/blob/main/feed.get.ts) package the data consistently across global and personalized feeds.

## Frequently Asked Questions

### What endpoints return the articles response structure?

The endpoints `GET /api/articles`, `GET /api/articles?author={username}`, `GET /api/articles?tag={tag}`, `GET /api/articles?favorited={username}`, and `GET /api/articles/feed` all return the same JSON structure containing the `articles` array and `articlesCount` integer.

### Why is the article body missing from the response?

The `body` field is excluded from list responses via the `omit: { body: true }` configuration in the query options to optimize performance. You must call `GET /api/articles/{slug}` to retrieve the full article body.

### How does the API calculate the favorited field?

The `favorited` boolean reflects whether the requesting user's ID appears in the article's favorites list. For unauthenticated requests, this value defaults to `false` as implemented in the `articleMapper` logic.

### What is the default pagination limit for article queries?

The default `limit` parameter is 10 articles per request, controlled by the route handlers in [`apps/api/server/routes/api/articles/index.get.ts`](https://github.com/gothinkster/realworld/blob/main/apps/api/server/routes/api/articles/index.get.ts) and [`feed.get.ts`](https://github.com/gothinkster/realworld/blob/main/feed.get.ts). Use the `offset` parameter to paginate through results.