Notifications
The account's alerts.
GET /notifications
Notifications
Scope: read. Newest first, by id.
Reading marks nothing read.
Parameters
| Name | Where | Description |
|---|---|---|
cursor | query | meta.next_cursor from the previous page. Up to 1024 characters. |
limit | query | Page size. Above 100 is treated as 100. At least 1. Default 25. |
unread | query | One of 0, 1. |
If-None-Match | header | An ETag from an earlier response. |
Example request
curl "https://www.seoclerk.com/api/v1/notifications" \
-H "Authorization: Bearer $SEOCLERKS_API_KEY"Response 200
A page of these in data, with meta.limit and meta.next_cursor.
| Field | Type | Description |
|---|---|---|
id | integer | |
sender_id | integer | |
resource_type | string | |
resource_id | integer | |
action | string | |
created_at | timestamp or null | |
read_at | timestamp or null |
{
"data": [
{
"id": 1024,
"sender_id": 1024,
"resource_type": "string",
"resource_id": 1024,
"action": "string",
"created_at": "2026-10-10T14:03:22Z",
"read_at": "2026-10-10T14:03:22Z"
}
],
"meta": {
"limit": 1,
"next_cursor": "string",
"request_id": "9f2c4e1ab07d3351"
}
}Errors
| Status | Codes |
|---|---|
| 400 | https_required key_in_query |
| 401 | account_unavailable invalid_credentials key_expired key_revoked |
| 403 | missing_scope |
| 404 | not_found |
| 405 | method_not_allowed |
| 422 | bad_cursor invalid_id invalid_parameter |
| 429 | rate_limited |
| 500 | internal_error |
PATCH /notifications
Mark every notification read
Scope: notifications:write, or the broad write. Idempotency-Key is optional.
Every unread notification, as the website's "mark all" does. One already read keeps its first read time.
Parameters
| Name | Where | Description |
|---|---|---|
Idempotency-Key | header | Makes a retry safe. Must match ^[A-Za-z0-9_.-]{1,64}$. |
Request body
| Field | Type | Description |
|---|---|---|
read required | boolean | Must be true. A notification cannot be marked unread. Always true. |
Example request
curl -X PATCH "https://www.seoclerk.com/api/v1/notifications" \
-H "Authorization: Bearer $SEOCLERKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"read":true}'Response 200
| Field | Type | Description |
|---|---|---|
marked | integer | How many were unread and are now read. |
{
"data": {
"marked": 1
},
"meta": {
"request_id": "9f2c4e1ab07d3351"
}
}Errors
PATCH /notifications/{id}
Mark a notification read
Scope: notifications:write, or the broad write. Idempotency-Key is optional.
The first read time is kept. A notification cannot be marked unread.
Parameters
| Name | Where | Description |
|---|---|---|
id required | path | At least 1. |
Idempotency-Key | header | Makes a retry safe. Must match ^[A-Za-z0-9_.-]{1,64}$. |
Request body
| Field | Type | Description |
|---|---|---|
read required | boolean | Must be true. A notification cannot be marked unread. Always true. |
Example request
curl -X PATCH "https://www.seoclerk.com/api/v1/notifications/1024" \
-H "Authorization: Bearer $SEOCLERKS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"read":true}'Response 200
| Field | Type | Description |
|---|---|---|
id | integer | |
read_at | timestamp or null |
{
"data": {
"id": 1024,
"read_at": "2026-10-10T14:03:22Z"
},
"meta": {
"request_id": "9f2c4e1ab07d3351"
}
}