# Social

Ratings, comments, favorites, and share links

## Endpoints

### GET /api/v1/favorites

**Authentication:** Required (Bearer JWT)

#### Responses

| Status | Description           |
| ------ | --------------------- |
| 200    | User favorites        |
| 401    | Unauthorized          |
| 500    | Internal server error |

---

### POST /api/v1/favorites

**Authentication:** Required (Bearer JWT)

#### Request Body

`Content-Type: application/json`

See `docs/api/openapi.json` for the full schema.

#### Responses

| Status | Description           |
| ------ | --------------------- |
| 200    | Added to favorites    |
| 401    | Unauthorized          |
| 500    | Internal server error |

---

### DELETE /api/v1/favorites/{media_id}

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name       | In   | Required | Description   |
| ---------- | ---- | -------- | ------------- |
| `media_id` | path | Yes      | Media item ID |

#### Responses

| Status | Description            |
| ------ | ---------------------- |
| 200    | Removed from favorites |
| 401    | Unauthorized           |
| 500    | Internal server error  |

---

### POST /api/v1/media/share

**Authentication:** Required (Bearer JWT)

#### Request Body

`Content-Type: application/json`

See `docs/api/openapi.json` for the full schema.

#### Responses

| Status | Description           |
| ------ | --------------------- |
| 200    | Share link created    |
| 400    | Bad request           |
| 401    | Unauthorized          |
| 500    | Internal server error |

---

### GET /api/v1/media/{id}/comments

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description   |
| ---- | ---- | -------- | ------------- |
| `id` | path | Yes      | Media item ID |

#### Responses

| Status | Description           |
| ------ | --------------------- |
| 200    | Media comments        |
| 401    | Unauthorized          |
| 500    | Internal server error |

---

### POST /api/v1/media/{id}/comments

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description   |
| ---- | ---- | -------- | ------------- |
| `id` | path | Yes      | Media item ID |

#### Request Body

`Content-Type: application/json`

See `docs/api/openapi.json` for the full schema.

#### Responses

| Status | Description           |
| ------ | --------------------- |
| 200    | Comment added         |
| 400    | Bad request           |
| 401    | Unauthorized          |
| 500    | Internal server error |

---

### POST /api/v1/media/{id}/rate

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description   |
| ---- | ---- | -------- | ------------- |
| `id` | path | Yes      | Media item ID |

#### Request Body

`Content-Type: application/json`

See `docs/api/openapi.json` for the full schema.

#### Responses

| Status | Description           |
| ------ | --------------------- |
| 200    | Rating saved          |
| 400    | Bad request           |
| 401    | Unauthorized          |
| 500    | Internal server error |

---

### GET /api/v1/media/{id}/ratings

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description   |
| ---- | ---- | -------- | ------------- |
| `id` | path | Yes      | Media item ID |

#### Responses

| Status | Description           |
| ------ | --------------------- |
| 200    | Media ratings         |
| 401    | Unauthorized          |
| 500    | Internal server error |

---

### GET /api/v1/shared/media/{token}

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name       | In    | Required | Description    |
| ---------- | ----- | -------- | -------------- |
| `token`    | path  | Yes      | Share token    |
| `password` | query | No       | Share password |

#### Responses

| Status | Description  |
| ------ | ------------ |
| 200    | Shared media |
| 401    | Unauthorized |
| 404    | Not found    |

---