Blog comments have two sides. Visitors submit comments via `POST /api/v1/posts/{idOrSlug}/comments` – these arrive **unapproved** and stay hidden until a moderator approves them. The store-scoped **moderation** endpoints under `/api/v1/post-comments` let you list every comment (including pending ones), approve or reject them, and delete spam.

## List Comments (Moderation)

```
GET /api/v1/post-comments
```

Returns blog comments across all posts for moderation, including those still pending approval. Use this to build a moderation queue. To submit a comment as a visitor, use `POST /api/v1/posts/{idOrSlug}/comments` instead.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 20 | Comments per page (1-100) |
| `offset` | `number` | 0 | Comments to skip |
| `query` | `string` | – | Search term for content, author, or email |
| `approved` | `boolean` | – | Filter by approval status (omit for all, including pending) |

```bash
curl \
  -H "Authorization: Bearer your_api_key" \
  "https://your-store.yns.store/api/v1/post-comments?approved=false&limit=20"
```

### Response (200)

```json
{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "postId": "0191abc0-0000-7000-8000-000000000100",
      "author": "Jane Doe",
      "email": "jane@example.com",
      "content": "Great write-up, thanks for sharing!",
      "approved": false,
      "userId": null,
      "post": {
        "id": "0191abc0-0000-7000-8000-000000000100",
        "title": "Spring Collection Preview",
        "slug": "spring-collection-preview"
      },
      "createdAt": "2024-06-15T10:30:00.000Z",
      "updatedAt": "2024-06-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 20
  }
}
```

---

## Get Comment

```
GET /api/v1/post-comments/{id}
```

Returns a single blog comment by UUID.

### Response (200)

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "postId": "0191abc0-0000-7000-8000-000000000100",
  "author": "Jane Doe",
  "email": "jane@example.com",
  "content": "Great write-up, thanks for sharing!",
  "approved": false,
  "userId": null,
  "post": {
    "id": "0191abc0-0000-7000-8000-000000000100",
    "title": "Spring Collection Preview",
    "slug": "spring-collection-preview"
  },
  "createdAt": "2024-06-15T10:30:00.000Z",
  "updatedAt": "2024-06-15T10:30:00.000Z"
}
```

### Not Found (404)

```json
{
  "error": "Comment not found"
}
```

---

## Approve or Reject Comment

```
PATCH /api/v1/post-comments/{id}
```

Sets the comment's `approved` flag. `true` publishes it on the storefront; `false` unpublishes/rejects it.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `approved` | `boolean` | Yes | `true` to publish, `false` to unpublish/reject |

```bash
curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"approved": true}' \
  https://your-store.yns.store/api/v1/post-comments/0191abc0-1234-7def-8000-000000000001
```

### Response (200)

Returns the updated comment with the new `approved` value.

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "postId": "0191abc0-0000-7000-8000-000000000100",
  "author": "Jane Doe",
  "email": "jane@example.com",
  "content": "Great write-up, thanks for sharing!",
  "approved": true,
  "userId": null,
  "post": {
    "id": "0191abc0-0000-7000-8000-000000000100",
    "title": "Spring Collection Preview",
    "slug": "spring-collection-preview"
  },
  "createdAt": "2024-06-15T10:30:00.000Z",
  "updatedAt": "2024-06-15T11:05:00.000Z"
}
```

---

## Delete Comment

```
DELETE /api/v1/post-comments/{id}
```

Hard-deletes the comment by UUID.

```bash
curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/post-comments/0191abc0-1234-7def-8000-000000000001
```

### Response (200)

```json
{
  "ok": true,
  "deleted": 1
}
```

---

## List Comments on a Post

```
GET /api/v1/posts/{idOrSlug}/comments
```

Returns **approved** comments for a single post, resolved by UUID or slug, newest first. This is the visitor-facing list shown on the storefront – pending comments are excluded.

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | `number` | 20 | Comments per page (1-100) |
| `offset` | `number` | 0 | Comments to skip |

```bash
curl \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/posts/spring-collection-preview/comments
```

### Response (200)

```json
{
  "data": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "author": "Jane Doe",
      "content": "Great write-up, thanks for sharing!",
      "createdAt": "2024-06-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "count": 1,
    "offset": 0,
    "limit": 20
  }
}
```

---

## Add a Comment to a Post

```
POST /api/v1/posts/{idOrSlug}/comments
```

Creates a comment on the given post (resolved by UUID or slug). New comments are created **unapproved** (`approved: false`) and stay hidden until a moderator approves them via `PATCH /api/v1/post-comments/{id}`.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `author` | `string` | Yes | Commenter display name (1-100 characters) |
| `email` | `string` | Yes | Commenter email address (valid email) |
| `content` | `string` | Yes | Comment text (1-5000 characters) |

```bash
curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"author": "Jane Doe", "email": "jane@example.com", "content": "Great write-up, thanks for sharing!"}' \
  https://your-store.yns.store/api/v1/posts/spring-collection-preview/comments
```

### Response (201)

```json
{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "author": "Jane Doe",
  "content": "Great write-up, thanks for sharing!",
  "createdAt": "2024-06-15T10:30:00.000Z"
}
```