# Comments

> 4 endpoints: list comment threads, retrieve a comment thread, reply to a comment thread, moderate a comment.

- [List comment threads](#list-comment-threads): `GET /v1/comments/threads`
- [Retrieve a comment thread](#retrieve-a-comment-thread): `GET /v1/comments/threads/{thread_id}`
- [Reply to a comment thread](#reply-to-a-comment-thread): `POST /v1/comments/threads/{thread_id}/replies`
- [Moderate a comment](#moderate-a-comment): `POST /v1/comments/threads/{thread_id}/comments/{comment_id}/moderate`

### List comment threads

`GET /v1/comments/threads`

Lists comment conversations on the accounts this key can reach, most recent activity first.

Permission: `comments:read`

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | Items per page, 1 to 100. (1 to 100, default 25) |
| `cursor` | string | No | The next_cursor of the previous page. (up to 512 characters) |
| `account_id` | string | No |  (up to 128 characters) |
| `status` | `needs_reply`, `completed`, `manual`, `sending`, `failed` | No |  |

#### Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"list"` | Yes |  |
| `data` | array of object | Yes |  |
| `data[].object` | `"comment_thread"` | Yes |  |
| `data[].id` | string | Yes |  (up to 128 characters) |
| `data[].account_id` | string | Yes |  (up to 128 characters) |
| `data[].network` | `youtube`, `tiktok`, `instagram`, `facebook`, `threads`, `bluesky`, `mastodon`, `pinterest`, `telegram`, `twitch`, `x`, `discord` | Yes |  |
| `data[].status` | `needs_reply`, `completed`, `manual`, `sending`, `failed` | Yes |  |
| `data[].video_id` | string or null | Yes |  |
| `data[].video_title` | string or null | Yes |  |
| `data[].conversation_version` | integer | Yes |  (-9007199254740991 to 9007199254740991) |
| `data[].latest_activity_at` | string | Yes | ISO 8601 date and time, UTC. |
| `data[].messages` | array of object | No |  |
| `has_more` | boolean | Yes |  |
| `next_cursor` | string or null | Yes |  |

```bash
curl https://api.nowscale.com/v1/comments/threads \
  -H "Authorization: Bearer $NOWSCALE_API_KEY"
```

### Retrieve a comment thread

`GET /v1/comments/threads/{thread_id}`

Returns one conversation with its messages, oldest first.

Permission: `comments:read`

#### Path parameters

| Name | Description |
| --- | --- |
| `thread_id` | The thread's id. |

#### Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"comment_thread"` | Yes |  |
| `id` | string | Yes |  (up to 128 characters) |
| `account_id` | string | Yes |  (up to 128 characters) |
| `network` | `youtube`, `tiktok`, `instagram`, `facebook`, `threads`, `bluesky`, `mastodon`, `pinterest`, `telegram`, `twitch`, `x`, `discord` | Yes |  |
| `status` | `needs_reply`, `completed`, `manual`, `sending`, `failed` | Yes |  |
| `video_id` | string or null | Yes |  |
| `video_title` | string or null | Yes |  |
| `conversation_version` | integer | Yes |  (-9007199254740991 to 9007199254740991) |
| `latest_activity_at` | string | Yes | ISO 8601 date and time, UTC. |
| `messages` | array of object | No |  |
| `messages[].object` | `"comment"` | Yes |  |
| `messages[].id` | string | Yes |  (up to 128 characters) |
| `messages[].author_role` | string | Yes |  |
| `messages[].author_name` | string | Yes |  |
| `messages[].text` | string or null | Yes |  |
| `messages[].moderation_status` | string | Yes |  |
| `messages[].url` | string or null | Yes |  |
| `messages[].published_at` | string | Yes | ISO 8601 date and time, UTC. |

```bash
curl https://api.nowscale.com/v1/comments/threads/THREAD_ID \
  -H "Authorization: Bearer $NOWSCALE_API_KEY"
```

### Reply to a comment thread

`POST /v1/comments/threads/{thread_id}/replies`

Posts a reply on the network, under the thread's top comment or the comment you name. Send the thread's conversation_version so a reply never lands on a conversation that changed since you read it. Replies go out as the account's owner; today only the person who connected the account can reply through it.

Permission: `comments:write` · Accepts `Idempotency-Key` · Answers `201`

#### Path parameters

| Name | Description |
| --- | --- |
| `thread_id` | The thread's id. |

#### Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string | Yes |  (up to 10000 characters) |
| `expected_conversation_version` | integer | Yes |  (0 to 9007199254740991) |
| `reply_to_comment_id` | string | No | The comment to answer. Defaults to the thread's top comment. (up to 128 characters) |

#### Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"comment_thread"` | Yes |  |
| `id` | string | Yes |  (up to 128 characters) |
| `account_id` | string | Yes |  (up to 128 characters) |
| `network` | `youtube`, `tiktok`, `instagram`, `facebook`, `threads`, `bluesky`, `mastodon`, `pinterest`, `telegram`, `twitch`, `x`, `discord` | Yes |  |
| `status` | `needs_reply`, `completed`, `manual`, `sending`, `failed` | Yes |  |
| `video_id` | string or null | Yes |  |
| `video_title` | string or null | Yes |  |
| `conversation_version` | integer | Yes |  (-9007199254740991 to 9007199254740991) |
| `latest_activity_at` | string | Yes | ISO 8601 date and time, UTC. |
| `messages` | array of object | No |  |
| `messages[].object` | `"comment"` | Yes |  |
| `messages[].id` | string | Yes |  (up to 128 characters) |
| `messages[].author_role` | string | Yes |  |
| `messages[].author_name` | string | Yes |  |
| `messages[].text` | string or null | Yes |  |
| `messages[].moderation_status` | string | Yes |  |
| `messages[].url` | string or null | Yes |  |
| `messages[].published_at` | string | Yes | ISO 8601 date and time, UTC. |

```bash
curl -X POST https://api.nowscale.com/v1/comments/threads/THREAD_ID/replies \
  -H "Authorization: Bearer $NOWSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ ... }'
```

### Moderate a comment

`POST /v1/comments/threads/{thread_id}/comments/{comment_id}/moderate`

Approves, hides, unhides, rejects or deletes a comment, or bans its author, where the network supports the action. Send the thread's conversation_version.

Permission: `comments:moderate` · Accepts `Idempotency-Key`

#### Path parameters

| Name | Description |
| --- | --- |
| `thread_id` | The thread's id. |
| `comment_id` | The comment's id. |

#### Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `action` | `approve`, `hide`, `unhide`, `reject`, `ban_author`, `delete` | Yes |  |
| `expected_conversation_version` | integer | Yes |  (0 to 9007199254740991) |

#### Response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | `"comment_thread"` | Yes |  |
| `id` | string | Yes |  (up to 128 characters) |
| `account_id` | string | Yes |  (up to 128 characters) |
| `network` | `youtube`, `tiktok`, `instagram`, `facebook`, `threads`, `bluesky`, `mastodon`, `pinterest`, `telegram`, `twitch`, `x`, `discord` | Yes |  |
| `status` | `needs_reply`, `completed`, `manual`, `sending`, `failed` | Yes |  |
| `video_id` | string or null | Yes |  |
| `video_title` | string or null | Yes |  |
| `conversation_version` | integer | Yes |  (-9007199254740991 to 9007199254740991) |
| `latest_activity_at` | string | Yes | ISO 8601 date and time, UTC. |
| `messages` | array of object | No |  |
| `messages[].object` | `"comment"` | Yes |  |
| `messages[].id` | string | Yes |  (up to 128 characters) |
| `messages[].author_role` | string | Yes |  |
| `messages[].author_name` | string | Yes |  |
| `messages[].text` | string or null | Yes |  |
| `messages[].moderation_status` | string | Yes |  |
| `messages[].url` | string or null | Yes |  |
| `messages[].published_at` | string | Yes | ISO 8601 date and time, UTC. |

```bash
curl -X POST https://api.nowscale.com/v1/comments/threads/THREAD_ID/comments/COMMENT_ID/moderate \
  -H "Authorization: Bearer $NOWSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ ... }'
```