# Notifications

Per-user in-app notifications driven by Laravel's database notification
channel. Notifications carry a `type` (Laravel class FQN) and a `data` payload
specific to the notification.

## List notifications

`GET /api/notifications`

Lists the notifications of the user the token belongs to, newest first.
Pass `unread=true` to restrict to unread items.

### Query parameters

- `unread` (boolean) — Only return unread notifications.
- `per_page` (integer) — Rows per page. Default 25, maximum 100. See [Lists, paging and filters](#lists-paging-and-filters).

### Example request

```bash
curl --request GET \
    --get "https://klozzo.com/api/notifications?unread=1&per_page=25" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200`

```json
{
    "data": [
        {
            "id": "9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234",
            "type": "App\\Notifications\\NewMessageReceived",
            "data": {
                "conversation_id": 17,
                "preview": "Hi Ada!"
            },
            "read_at": null,
            "created_at": "2026-06-05T13:42:00+00:00"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 4,
        "per_page": 25,
        "total": 87,
        "unread_count": 12
    }
}
```

## Unread count

`GET /api/notifications/unread-count`

Returns how many notifications you have unread, as a single integer — a
lightweight endpoint for badge polling.

### Example request

```bash
curl --request GET \
    --get "https://klozzo.com/api/notifications/unread-count" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200`

```json
{
    "unread_count": 12
}
```

## Mark a notification as read

`POST /api/notifications/{id}/read`

Marks one notification as read. Idempotent: marking an already-read
notification is a no-op (returns the
existing read_at).

### Path parameters

- `id` (string, required) — Notification UUID.

### Example request

```bash
curl --request POST \
    "https://klozzo.com/api/notifications/9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234/read" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200`

```json
{
    "data": {
        "id": "9c8b9e15-79b7-4a2a-9b2c-0f56b2b0a234",
        "type": "App\\Notifications\\NewMessageReceived",
        "data": {
            "conversation_id": 17,
            "preview": "Hi Ada!"
        },
        "read_at": "2026-06-05T13:43:00+00:00",
        "created_at": "2026-06-05T13:42:00+00:00"
    },
    "unread_count": 11
}
```

### Response `404` — Not yours, or the UUID does not exist

```json
{
    "message": "Not Found"
}
```

## Mark all notifications as read

`POST /api/notifications/read-all`

Marks every notification of the user the token belongs to as read, in one
call. It affects **your** notifications only — the
ones belonging to the user the token was issued for — so it can never
clear somebody else's inbox.

Marking everything read is not the same as deleting: the notifications
stay readable, they just stop counting.

### Example request

```bash
curl --request POST \
    "https://klozzo.com/api/notifications/read-all" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
```

### Response `200`

```json
{
    "unread_count": 0
}
```

## Update notification preferences

`PUT /api/notifications/preferences`

Updates your notification preferences. Currently only the `muted` list is
supported — notifications whose `type`
matches an entry in the list are skipped at delivery time. Provide the
full desired list (full-replace, not append).

### Body parameters

- `muted` (string[]) — Notification types to mute.

### Example request

```bash
curl --request PUT \
    "https://klozzo.com/api/notifications/preferences" \
    --header "Authorization: Bearer {YOUR_API_TOKEN}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"muted\": [
        \"App\\\\Notifications\\\\NewMessageReceived\"
    ]
}"
```

### Response `200`

```json
{
    "data": {
        "muted": [
            "App\\Notifications\\NewMessageReceived"
        ]
    }
}
```

### Response `422` — Not a list

```json
{
    "message": "Muted debe ser una lista.",
    "errors": {
        "muted": [
            "Muted debe ser una lista."
        ]
    }
}
```