pinakes/docs/api/shares.md

# Shares

Media sharing and notifications

## Endpoints

### GET /api/v1/notifications/shares

Get unread share notifications GET /api/notifications/shares

**Authentication:** Required (Bearer JWT)

#### Responses

| Status | Description          |
| ------ | -------------------- |
| 200    | Unread notifications |
| 401    | Unauthorized         |

---

### POST /api/v1/notifications/shares/read-all

Mark all notifications as read POST /api/notifications/shares/read-all

**Authentication:** Required (Bearer JWT)

#### Responses

| Status | Description                      |
| ------ | -------------------------------- |
| 200    | All notifications marked as read |
| 401    | Unauthorized                     |

---

### POST /api/v1/notifications/shares/{id}/read

Mark a notification as read POST /api/notifications/shares/{id}/read

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description     |
| ---- | ---- | -------- | --------------- |
| `id` | path | Yes      | Notification ID |

#### Responses

| Status | Description                 |
| ------ | --------------------------- |
| 200    | Notification marked as read |
| 401    | Unauthorized                |

---

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

Access a public shared resource GET /api/shared/{token}

**Authentication:** Required (Bearer JWT)

#### Parameters

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

#### Responses

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

---

### POST /api/v1/shares

Create a new share POST /api/shares

**Authentication:** Required (Bearer JWT)

#### Request Body

`Content-Type: application/json`

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

#### Responses

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

---

### POST /api/v1/shares/batch/delete

Batch delete shares POST /api/shares/batch/delete

**Authentication:** Required (Bearer JWT)

#### Request Body

`Content-Type: application/json`

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

#### Responses

| Status | Description    |
| ------ | -------------- |
| 200    | Shares deleted |
| 400    | Bad request    |
| 401    | Unauthorized   |
| 403    | Forbidden      |

---

### GET /api/v1/shares/incoming

List incoming shares (shares shared with me) GET /api/shares/incoming

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name     | In    | Required | Description       |
| -------- | ----- | -------- | ----------------- |
| `offset` | query | No       | Pagination offset |
| `limit`  | query | No       | Pagination limit  |

#### Responses

| Status | Description     |
| ------ | --------------- |
| 200    | Incoming shares |
| 401    | Unauthorized    |

---

### GET /api/v1/shares/outgoing

List outgoing shares (shares I created) GET /api/shares/outgoing

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name     | In    | Required | Description       |
| -------- | ----- | -------- | ----------------- |
| `offset` | query | No       | Pagination offset |
| `limit`  | query | No       | Pagination limit  |

#### Responses

| Status | Description     |
| ------ | --------------- |
| 200    | Outgoing shares |
| 401    | Unauthorized    |

---

### GET /api/v1/shares/{id}

Get share details GET /api/shares/{id}

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description |
| ---- | ---- | -------- | ----------- |
| `id` | path | Yes      | Share ID    |

#### Responses

| Status | Description   |
| ------ | ------------- |
| 200    | Share details |
| 401    | Unauthorized  |
| 403    | Forbidden     |
| 404    | Not found     |

---

### PATCH /api/v1/shares/{id}

Update a share PATCH /api/shares/{id}

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description |
| ---- | ---- | -------- | ----------- |
| `id` | path | Yes      | Share ID    |

#### Request Body

`Content-Type: application/json`

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

#### Responses

| Status | Description   |
| ------ | ------------- |
| 200    | Share updated |
| 401    | Unauthorized  |
| 403    | Forbidden     |
| 404    | Not found     |

---

### DELETE /api/v1/shares/{id}

Delete (revoke) a share DELETE /api/shares/{id}

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name | In   | Required | Description |
| ---- | ---- | -------- | ----------- |
| `id` | path | Yes      | Share ID    |

#### Responses

| Status | Description   |
| ------ | ------------- |
| 204    | Share deleted |
| 401    | Unauthorized  |
| 403    | Forbidden     |
| 404    | Not found     |

---

### GET /api/v1/shares/{id}/activity

Get share activity log GET /api/shares/{id}/activity

**Authentication:** Required (Bearer JWT)

#### Parameters

| Name     | In    | Required | Description       |
| -------- | ----- | -------- | ----------------- |
| `id`     | path  | Yes      | Share ID          |
| `offset` | query | No       | Pagination offset |
| `limit`  | query | No       | Pagination limit  |

#### Responses

| Status | Description    |
| ------ | -------------- |
| 200    | Share activity |
| 401    | Unauthorized   |
| 403    | Forbidden      |
| 404    | Not found      |

---