Forum API References

Get All Forum Posts

URL: https://api.gradual-api.com/public-api/v1/forum/posts

HTTP Method: GET

Content type: application/json

Tier: Medium

Query Parameters:

pageNum, integer, optional, page number (minimum 1, defaults to 1)
pageSize, integer, optional, number of results per page (1–100, defaults to 20)
sortBy, string, optional, field to sort by (currently only createdAt is supported, defaults to createdAt)
sortOrder, string, optional, sort direction: asc or desc (defaults to desc)

Response Example:

{
    "size": 2,
    "pageNumber": 1,
    "pageSize": 20,
    "sortBy": "createdAt",
    "sortOrder": "desc",
    "results": [
        {
            "id": "6553ce608b3f645e79d95034",
            "slug": "how-to-get-started",
            "title": "How to get started",
            "content": "Here is a guide on how to get started...",
            "type": "discussion",
            "active": true,
            "viewCount": 42,
            "commentsCount": 3,
            "reactionSummary": {
                "totalCount": 5,
                "positiveCount": 5,
                "negativeCount": 0,
                "details": {}
            },
            "tags": ["Getting Started", "Guide"],
            "posterUrl": "",
            "locked": false,
            "answered": false,
            "createdAt": "2024-11-14T10:30:00.000Z",
            "lastEditAt": "2024-11-14T10:30:00.000Z",
            "lastCommentedAt": "2024-11-15T08:00:00.000Z",
            "board": "General Discussion",
            "poster": {
                "email": "[email protected]",
                "firstName": "Jane",
                "lastName": "Doe",
                "pictureUrl": "https://example.com/avatar.jpg",
                "headline": "Software Engineer at Test Company"
            }
        },
        {
            "id": "6553ce608b3f645e79d95035",
            "slug": "feature-request-dark-mode",
            "title": "Feature Request: Dark Mode",
            "content": "It would be great to have a dark mode option...",
            "type": "question",
            "active": true,
            "viewCount": 18,
            "commentsCount": 1,
            "reactionSummary": {
                "totalCount": 2,
                "positiveCount": 2,
                "negativeCount": 0,
                "details": {}
            },
            "tags": ["Feature Request"],
            "posterUrl": "",
            "locked": false,
            "answered": true,
            "createdAt": "2024-11-13T14:00:00.000Z",
            "lastEditAt": "2024-11-13T14:00:00.000Z",
            "lastCommentedAt": "2024-11-14T09:15:00.000Z",
            "board": "Ideas & Feedback",
            "poster": {
                "email": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pictureUrl": "",
                "headline": "Product Manager"
            }
        }
    ]
}

Forum Post Fields:

id, string, the post's unique identifier
slug, string, URL-friendly identifier for the post
title, string, the post title
content, string, the post body content
type, string, post type (e.g. discussion, question)
active, boolean, whether the post is active
viewCount, number, total number of views
commentsCount, number, total number of comments
reactionSummary, object, aggregated reaction counts (totalCount, positiveCount, negativeCount, details)
tags, array of strings, tag names associated with the post
board, string, name of the forum board the post belongs to
poster, object, author information (email, firstName, lastName, pictureUrl, headline)
posterUrl, string, URL of the post's cover image (if any)
locked, boolean, whether the post is locked for new comments
answered, boolean, whether the post has an accepted answer (relevant for question type posts)
createdAt, string, ISO 8601 timestamp of when the post was created
lastEditAt, string, ISO 8601 timestamp of the last edit
lastCommentedAt, string, ISO 8601 timestamp of the last comment

Get Forum Post by ID

URL: https://api.gradual-api.com/public-api/v1/forum/posts/:postId

HTTP Method: GET

Content type: application/json

Tier: Light

Path Parameters:

postId, string, required, the post's ID

Response Example:

{
    "id": "6553ce608b3f645e79d95034",
    "slug": "how-to-get-started",
    "title": "How to get started",
    "content": "Here is a guide on how to get started...",
    "type": "discussion",
    "active": true,
    "viewCount": 42,
    "commentsCount": 3,
    "reactionSummary": {
        "totalCount": 5,
        "positiveCount": 5,
        "negativeCount": 0,
        "details": {}
    },
    "tags": ["Getting Started", "Guide"],
    "posterUrl": "",
    "locked": false,
    "answered": false,
    "createdAt": "2024-11-14T10:30:00.000Z",
    "lastEditAt": "2024-11-14T10:30:00.000Z",
    "lastCommentedAt": "2024-11-15T08:00:00.000Z",
    "board": "General Discussion",
    "poster": {
        "email": "[email protected]",
        "firstName": "Jane",
        "lastName": "Doe",
        "pictureUrl": "https://example.com/avatar.jpg",
        "headline": "Software Engineer at Test Company"
    }
}

Notes:

The response fields are the same as a single item in the Get All Forum Posts response.
Returns 400 if the post is not found or the poster's account has been archived.

Get All Forum Comments

URL: https://api.gradual-api.com/public-api/v1/forum/comments

HTTP Method: GET

Content type: application/json

Tier: Medium

Query Parameters:

pageNum, integer, optional, page number (minimum 1, defaults to 1)
pageSize, integer, optional, number of results per page (1–100, defaults to 20)
sortBy, string, optional, field to sort by (currently only createdAt is supported, defaults to createdAt)
sortOrder, string, optional, sort direction: asc or desc (defaults to desc)

Response Example:

{
    "size": 2,
    "pageNumber": 1,
    "pageSize": 20,
    "sortBy": "createdAt",
    "sortOrder": "desc",
    "results": [
        {
            "id": "6553ce608b3f645e79d95040",
            "content": "Great post! This was very helpful.",
            "createdAt": "2024-11-15T08:00:00.000Z",
            "lastEditAt": "2024-11-15T08:00:00.000Z",
            "acceptedAsAnswer": false,
            "status": "active",
            "postId": "6553ce608b3f645e79d95034",
            "postSlug": "how-to-get-started",
            "postTitle": "How to get started",
            "board": "General Discussion",
            "commenter": {
                "email": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pictureUrl": "https://example.com/avatar.jpg",
                "headline": "Product Manager"
            }
        },
        {
            "id": "6553ce608b3f645e79d95041",
            "content": "You can enable it in Settings > Appearance.",
            "createdAt": "2024-11-14T09:15:00.000Z",
            "lastEditAt": "2024-11-14T09:15:00.000Z",
            "acceptedAsAnswer": true,
            "status": "active",
            "postId": "6553ce608b3f645e79d95035",
            "postSlug": "feature-request-dark-mode",
            "postTitle": "Feature Request: Dark Mode",
            "board": "Ideas & Feedback",
            "commenter": {
                "email": "[email protected]",
                "firstName": "Jane",
                "lastName": "Doe",
                "pictureUrl": "",
                "headline": "Software Engineer at Test Company"
            }
        }
    ]
}

Forum Comment Fields:

id, string, the comment's unique identifier
content, string, the comment body
createdAt, string, ISO 8601 timestamp of when the comment was created
lastEditAt, string, ISO 8601 timestamp of the last edit
acceptedAsAnswer, boolean, whether the comment has been accepted as the answer to the post
status, string, the comment's status
postId, string, ID of the parent post
postSlug, string, URL-friendly identifier of the parent post
postTitle, string, title of the parent post
board, string, name of the forum board the parent post belongs to
commenter, object, author information (email, firstName, lastName, pictureUrl, headline)

Notes:

This endpoint returns comments across all posts. To get comments for a specific post, use Get Comments by Post ID instead.

Get Comments by Post ID

URL: https://api.gradual-api.com/public-api/v1/forum/posts/:postId/comments

HTTP Method: GET

Content type: application/json

Tier: Medium

Path Parameters:

postId, string, required, the post's ID

Query Parameters:

pageNum, integer, optional, page number (minimum 1, defaults to 1)
pageSize, integer, optional, number of results per page (1–100, defaults to 20)
sortBy, string, optional, field to sort by (currently only createdAt is supported, defaults to createdAt)
sortOrder, string, optional, sort direction: asc or desc (defaults to desc)

Response Example:

{
    "size": 2,
    "pageNumber": 1,
    "pageSize": 20,
    "sortBy": "createdAt",
    "sortOrder": "desc",
    "results": [
        {
            "id": "6553ce608b3f645e79d95040",
            "content": "Great post! This was very helpful.",
            "createdAt": "2024-11-15T08:00:00.000Z",
            "lastEditAt": "2024-11-15T08:00:00.000Z",
            "acceptedAsAnswer": false,
            "status": "active",
            "postId": "6553ce608b3f645e79d95034",
            "postSlug": "how-to-get-started",
            "postTitle": "How to get started",
            "board": "General Discussion",
            "commenter": {
                "email": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pictureUrl": "https://example.com/avatar.jpg",
                "headline": "Product Manager"
            }
        },
        {
            "id": "6553ce608b3f645e79d95041",
            "content": "Thanks for sharing!",
            "createdAt": "2024-11-14T16:30:00.000Z",
            "lastEditAt": "2024-11-14T16:30:00.000Z",
            "acceptedAsAnswer": false,
            "status": "active",
            "postId": "6553ce608b3f645e79d95034",
            "postSlug": "how-to-get-started",
            "postTitle": "How to get started",
            "board": "General Discussion",
            "commenter": {
                "email": "[email protected]",
                "firstName": "Jane",
                "lastName": "Doe",
                "pictureUrl": "",
                "headline": "Software Engineer at Test Company"
            }
        }
    ]
}

Notes:

The response fields are the same as Get All Forum Comments, but scoped to a single post.
Returns 400 if the post is not found.

Content

Settings