# Notifications API

## Endpoints

### List Notifications

```
GET /api/v1/notifications
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `all` | boolean | Show all notifications (including read) |
| `status-types` | string[] | Filter by status: `unread`, `read`, `pinned` |
| `subject-type` | string[] | Filter by subject: `issue`, `pull`, `commit`, `repository` |
| `since` | string | Only show notifications updated after (ISO 8601) |
| `before` | string | Only show notifications updated before (ISO 8601) |
| `page` | integer | Page number (1-based) |
| `limit` | integer | Page size |

```bash
# List unread notifications
curl -s "${FORGEJO_URL}/api/v1/notifications" \
  -H "Authorization: token ${FORGEJO_PAT}"

# List all notifications including read
curl -s "${FORGEJO_URL}/api/v1/notifications?all=true" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Filter by status type
curl -s "${FORGEJO_URL}/api/v1/notifications?status-types=unread&status-types=pinned" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Filter by subject type (only issues)
curl -s "${FORGEJO_URL}/api/v1/notifications?subject-type=issue" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Notifications since a date
curl -s "${FORGEJO_URL}/api/v1/notifications?since=2024-01-01T00:00:00Z" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Paginated
curl -s "${FORGEJO_URL}/api/v1/notifications?page=2&limit=20" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### Mark All Notifications as Read

```
PUT /api/v1/notifications
```

**Query parameters** (per Swagger spec — these are query params, not body fields):

| Parameter | Type | Description |
|-----------|------|-------------|
| `last_read_at` | string | Mark notifications read up to this time (ISO 8601) |
| `all` | boolean | If true, mark all notifications (default: false) |
| `status-types` | string[] | Only mark notifications with these statuses (`unread`, `read`, `pinned`) |
| `to-status` | string | Target status: `read`, `unread`, `pinned` (default: `read`) |

> **Note:** The canonical form per the Swagger spec uses query parameters with hyphenated names (`to-status`, `status-types`). Some Forgejo versions also accept a JSON body with underscored names (`to_status`, `status_types`), but query parameters are the standard approach.

```bash
# Mark all as read (query parameter form — canonical)
curl -s -X PUT "${FORGEJO_URL}/api/v1/notifications?to-status=read" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Mark all unread notifications as read up to a specific time
curl -s -X PUT "${FORGEJO_URL}/api/v1/notifications?last_read_at=2024-06-01T00:00:00Z&status-types=unread&to-status=read" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Alternative: JSON body form (also works on most Forgejo versions)
curl -s -X PUT "${FORGEJO_URL}/api/v1/notifications" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "last_read_at": "2024-06-01T00:00:00Z",
    "status_types": ["unread"],
    "to_status": "read"
  }'
```

---

### Check for New Notifications

```
GET /api/v1/notifications/new
```

Returns a count of new/unread notifications.

```bash
curl -s "${FORGEJO_URL}/api/v1/notifications/new" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

**Response:**

```json
{
  "new": 5
}
```

---

### Get Notification Thread

```
GET /api/v1/notifications/threads/{id}
```

```bash
curl -s "${FORGEJO_URL}/api/v1/notifications/threads/{thread_id}" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### Mark Notification Thread as Read

```
PATCH /api/v1/notifications/threads/{id}
```

**Query parameter** (per Swagger spec):

| Parameter | Type | Description |
|-----------|------|-------------|
| `to-status` | string | Target status: `read`, `unread`, `pinned` (default: `read`) |

```bash
# Mark thread as read (query parameter form — canonical)
curl -s -X PATCH "${FORGEJO_URL}/api/v1/notifications/threads/{thread_id}?to-status=read" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Pin a notification thread
curl -s -X PATCH "${FORGEJO_URL}/api/v1/notifications/threads/{thread_id}?to-status=pinned" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Alternative: JSON body form
curl -s -X PATCH "${FORGEJO_URL}/api/v1/notifications/threads/{thread_id}" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"to_status": "read"}'
```

---

### List Repository Notifications

```
GET /api/v1/repos/{owner}/{repo}/notifications
```

Same parameters as the global notifications endpoint.

```bash
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/notifications" \
  -H "Authorization: token ${FORGEJO_PAT}"

# With filters
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/notifications?status-types=unread&subject-type=pull" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

---

### Mark Repository Notifications as Read

```
PUT /api/v1/repos/{owner}/{repo}/notifications
```

Same query parameters as the global mark-read endpoint (`last_read_at`, `all`, `status-types`, `to-status`).

```bash
# Canonical query parameter form
curl -s -X PUT "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/notifications?to-status=read" \
  -H "Authorization: token ${FORGEJO_PAT}"

# Alternative JSON body form
curl -s -X PUT "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/notifications" \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{"to_status": "read"}'
```

---

## Notification Object

```json
{
  "id": 42,
  "subject": {
    "title": "Fix login bug",
    "url": "https://{FORGEJO_HOST}/api/v1/repos/{owner}/{repo}/issues/{index}",
    "type": "Issue",
    "state": "open",
    "html_url": "https://{FORGEJO_HOST}/{owner}/{repo}/issues/{index}",
    "latest_comment_url": "https://{FORGEJO_HOST}/api/v1/repos/{owner}/{repo}/issues/comments/88",
    "latest_comment_html_url": "https://{FORGEJO_HOST}/{owner}/{repo}/issues/{index}#issuecomment-88"
  },
  "repository": {
    "id": 1,
    "full_name": "{owner}/{repo}",
    "html_url": "https://{FORGEJO_HOST}/{owner}/{repo}"
  },
  "unread": true,
  "pinned": false,
  "updated_at": "2024-03-15T10:30:00Z",
  "url": "https://{FORGEJO_HOST}/api/v1/notifications/threads/{thread_id}"
}
```

### Subject Types

| Type | Description |
|------|-------------|
| `Issue` | Issue notification |
| `Pull` | Pull request notification |
| `Commit` | Commit notification |
| `Repository` | Repository notification |

### Subject States

- `open` - Issue/PR is open
- `closed` - Issue/PR is closed
- `merged` - PR was merged
