Comments API

Create, read, update, and delete comments. Base URL: https://api.threadline.io/v1

Identify a thread with thread_url and site_id. Requires API key or session unless marked PUBLIC.

GET/v1/commentsPUBLIC

List comments for a thread. Query params: thread_url (required), site_id (required), sort, page, limit.

Example response

{
  "comments": [{
    "id": "cmt_abc123",
    "content": "Great article!",
    "author_name": "Jane",
    "upvotes": 12,
    "downvotes": 1,
    "reaction_counts": {
      "funny": 1,
      "interesting": 3,
      "insightful": 2
    },
    "thread_url": "https://example.com/blog/post-1",
    "site_id": "site_abc123",
    "parent_id": null,
    "created_at": "2025-01-15T10:30:00Z",
    "replies": [{
      "id": "cmt_reply1",
      "content": "Agreed.",
      "author_name": "Sam",
      "upvotes": 2,
      "reaction_counts": {},
      "replies": []
    }]
  }],
  "total": 47,
  "page": 1
}

POST/v1/comments

// Request body
{
  "thread_url": "https://example.com/blog/post-1",
  "site_id": "site_abc123",
  "content": "Great article! I especially liked...",
  "parent_id": null
}

Example response

{
  "id": "cmt_new123",
  "content": "Great article! I especially liked...",
  "author_name": "Jane",
  "upvotes": 0,
  "reaction_counts": {},
  "thread_url": "https://example.com/blog/post-1",
  "site_id": "site_abc123",
  "parent_id": null,
  "replies": [],
  "created_at": "2025-01-15T12:00:00Z"
}

PATCH/v1/comments/:id

Update your own comment body.

{ "content": "Updated text..." }

Example response

{
  "id": "cmt_abc123",
  "content": "Updated text...",
  "author_name": "Jane",
  "upvotes": 12,
  "reaction_counts": { "interesting": 3 },
  "is_edited": true,
  "replies": []
}

DELETE/v1/comments/:id

Soft-deletes (content becomes null / marked deleted). Only author or moderator.

POST/v1/comments/:id/vote

{ "vote_type": "up" }
// vote_type: "up" | "down"

Example response

{
  "upvotes": 13,
  "downvotes": 1,
  "user_vote": "up",
  "liked_by_site_owner": false
}

POST/v1/comments/:id/react

{ "reaction_type": "insightful" }
// Toggle: same reaction again removes it.

Example response

{
  "reaction_counts": {
    "funny": 1,
    "interesting": 3,
    "insightful": 3
  },
  "user_reaction": "insightful"
}

PATCH/v1/comments/:id/moderate

Moderator actions: approve, remove, spam, shadow_ban, unhide.

{ "action": "approve", "reason": "Looks good" }

Example response

{
  "id": "cmt_abc123",
  "moderation_status": null,
  "action": "approve",
  "content": "Great article!",
  "author_name": "Jane"
}

Content: Comment bodies use plain content (and optional rich text). Nested replies are returned under replies.