Skip to main content

​
Overview

Discussions provide threaded commenting on stories and profiles. Comments support nested replies (up to 6 levels deep), voting, and moderation.

​
Discussion Features

Nested Threads

Up to 6 levels of nested replies

Voting

Upvote and downvote comments

Moderation

Hide, pin, and lock threads (contributor+ only)

Real-time

Live comment updates

​
List Story Discussion Comments

GET /{locale}/stories/{slug}/_discussions
List top-level comments for a story’s discussion thread.
​
slug
string
required
Story slug
​
sort
string
default:"hot"
Sort mode: hot, newest, oldest
​
limit
integer
default:"25"
Number of comments per page (max 100)
​
offset
integer
default:"0"
Number of comments to skip
curl "http://localhost:8080/en/stories/introducing-aya/_discussions?sort=hot&limit=10"
Response: 
{
  "data": {
    "thread": {
      "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "story_id": "01ARZ3NDEKTSV4RRFFQ69G5FAW",
      "is_locked": false,
      "comment_count": 42,
      "created_at": "2024-01-15T10:30:00Z"
    },
    "comments": [
      {
        "id": "01ARZ3NDEKTSV4RRFFQ69G5FAX",
        "thread_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
        "parent_id": null,
        "author_profile_id": "01ARZ3NDEKTSV4RRFFQ69G5FAY",
        "author_profile_slug": "john-doe",
        "author_profile_title": "John Doe",
        "author_profile_picture_uri": "https://avatars.githubusercontent.com/u/12345",
        "content": "Great article! Looking forward to trying this out.",
        "depth": 0,
        "vote_score": 15,
        "upvote_count": 17,
        "downvote_count": 2,
        "reply_count": 3,
        "is_pinned": false,
        "is_hidden": false,
        "is_edited": false,
        "viewer_vote_direction": 1,
        "created_at": "2024-01-15T11:00:00Z"
      }
    ]
  },
  "error": null
}
​
thread
object
Thread metadata
​
thread.id
string
Thread ID
​
thread.is_locked
boolean
Whether new comments are disabled
​
thread.comment_count
integer
Total comment count (including nested)
​
comments
array
Top-level comments
​
comments[].vote_score
integer
Net vote score (upvotes - downvotes)
​
comments[].viewer_vote_direction
integer
Current user’s vote: 1 (upvote), -1 (downvote), 0 (no vote)
​
comments[].depth
integer
Nesting depth (0 = top-level, max 6)
​
comments[].reply_count
integer
Number of direct replies

​
List Profile Discussion Comments

GET /{locale}/profiles/{slug}/_discussions
List top-level comments for a profile’s discussion thread. Same parameters and response format as story discussions.

​
List Comment Replies

GET /{locale}/discussions/comments/{commentId}/replies
List replies to a specific comment.
​
commentId
string
required
Parent comment ID
​
sort
string
default:"hot"
Sort mode: hot, newest, oldest
​
limit
integer
default:"25"
Number of replies per page
curl "http://localhost:8080/en/discussions/comments/01ARZ3NDEKTSV4RRFFQ69G5FAX/replies"
Response: 
{
  "data": {
    "comments": [
      {
        "id": "01ARZ3NDEKTSV4RRFFQ69G5FAZ",
        "parent_id": "01ARZ3NDEKTSV4RRFFQ69G5FAX",
        "content": "Thanks! Let me know what you think.",
        "depth": 1,
        "vote_score": 5,
        "reply_count": 0
      }
    ]
  }
}

​
Create Comment

POST /{locale}/stories/{slug}/_discussions
POST /{locale}/profiles/{slug}/_discussions
Authentication Required
Create a new comment on a story or profile discussion.
​
content
string
required
Comment content (3-10,000 characters)
​
parent_id
string
Parent comment ID for replies (omit for top-level)
curl -X POST "http://localhost:8080/en/stories/introducing-aya/_discussions" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Great article! Looking forward to trying this out."
  }'
Response: 
{
  "data": {
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAX",
    "thread_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "parent_id": null,
    "author_profile_id": "01ARZ3NDEKTSV4RRFFQ69G5FAY",
    "author_profile_slug": "john-doe",
    "author_profile_title": "John Doe",
    "content": "Great article! Looking forward to trying this out.",
    "depth": 0,
    "vote_score": 0,
    "upvote_count": 0,
    "downvote_count": 0,
    "reply_count": 0,
    "viewer_vote_direction": 0,
    "created_at": "2024-03-07T10:30:00Z"
  }
}
Nesting LimitComments can be nested up to 6 levels deep. Attempting to reply beyond this depth will return a 400 error.
Thread LockedIf the discussion thread is locked, the API will return a 403 error. Only contributors+ can lock/unlock threads.

​
Edit Comment

PUT /{locale}/discussions/comments/{commentId}
Authentication Required - Must be comment author
Edit your own comment.
​
commentId
string
required
Comment ID to edit
​
content
string
required
New comment content (3-10,000 characters)
curl -X PUT "http://localhost:8080/en/discussions/comments/01ARZ3NDEKTSV4RRFFQ69G5FAX" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated comment text"}'
Response: 
{
  "data": {
    "status": "ok"
  }
}

​
Delete Comment

DELETE /{locale}/discussions/comments/{commentId}
Authentication Required - Must be comment author or contributor+
Delete a comment. Authors can delete their own comments; contributors+ can delete any comment.
​
commentId
string
required
Comment ID to delete
​
profile_slug
string
Profile slug (required for contributor+ deletion to verify permissions)
curl -X DELETE "http://localhost:8080/en/discussions/comments/01ARZ3NDEKTSV4RRFFQ69G5FAX?profile_slug=my-profile" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Vote on Comment

POST /{locale}/discussions/comments/{commentId}/vote
Authentication Required
Upvote or downvote a comment. Voting again with the same direction removes the vote.
​
commentId
string
required
Comment ID to vote on
​
direction
integer
required
Vote direction: 1 (upvote) or -1 (downvote)
curl -X POST "http://localhost:8080/en/discussions/comments/01ARZ3NDEKTSV4RRFFQ69G5FAX/vote" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"direction": 1}'
Response: 
{
  "data": {
    "vote_score": 16,
    "viewer_vote_direction": 1
  }
}
​
vote_score
integer
New net vote score (upvotes - downvotes)
​
viewer_vote_direction
integer
Your current vote: 1, -1, or 0 (removed)
Toggle VotingVoting with the same direction again removes your vote:
  • First upvote: direction = 1
  • Second upvote: direction = 0 (vote removed)

​
Hide/Unhide Comment

POST /{locale}/discussions/comments/{commentId}/hide
Authentication Required - Requires contributor+ access
Hide or unhide a comment. Hidden comments are only visible to contributors+.
​
is_hidden
boolean
required
Hide status
​
profile_slug
string
required
Profile slug to check permissions
curl -X POST "http://localhost:8080/en/discussions/comments/01ARZ3NDEKTSV4RRFFQ69G5FAX/hide" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_hidden": true, "profile_slug": "my-profile"}'

​
Pin/Unpin Comment

POST /{locale}/discussions/comments/{commentId}/pin
Authentication Required - Requires contributor+ access
Pin or unpin a comment to the top of the discussion.
​
is_pinned
boolean
required
Pin status
​
profile_slug
string
required
Profile slug to check permissions
curl -X POST "http://localhost:8080/en/discussions/comments/01ARZ3NDEKTSV4RRFFQ69G5FAX/pin" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_pinned": true, "profile_slug": "my-profile"}'

​
Lock/Unlock Thread

POST /{locale}/discussions/threads/{threadId}/lock
Authentication Required - Requires contributor+ access
Lock or unlock a discussion thread. Locked threads prevent new comments.
​
threadId
string
required
Thread ID to lock/unlock
​
is_locked
boolean
required
Lock status
​
profile_slug
string
required
Profile slug to check permissions
curl -X POST "http://localhost:8080/en/discussions/threads/01ARZ3NDEKTSV4RRFFQ69G5FAV/lock" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_locked": true, "profile_slug": "my-profile"}'

​
Discussion Best Practices

Moderation Guidelines
  • Pin important announcements or answers
  • Hide spam or off-topic comments
  • Lock threads that become unproductive
  • Use vote sorting to surface quality content
Performance Tips
  • Paginate long discussions with limit/offset
  • Load replies on-demand (don’t fetch all nested comments upfront)
  • Use sort=hot for active discussions
  • Cache thread metadata separately from comments

Build docs developers (and LLMs) love

Get started for freeTalk to us