Skip to main content
The in-app notification feed. Powers the bell icon in console.bytespike.ai — the same five event types you can subscribe to via webhooks (/me/webhooks) also accrue here for in-app display unless you’ve muted them. Free. For push-style consumption, prefer webhooks — this endpoint is a polling fallback (e.g. for an IDE extension or a status bar where running a webhook receiver isn’t practical).

​
Endpoint family

MethodPathPurpose
GET/api/v1/me/notifications?unread=&type=&page=&page_size=List notifications
GET/api/v1/me/notifications/unread-countJust the unread counter
POST/api/v1/me/notifications/:id/mark-readMark a single notification read
POST/api/v1/me/notifications/mark-all-readMark every unread one read
All require a logged-in key. Mark-read operations are free.

​
List

curl 'https://llm.bytespike.ai/api/v1/me/notifications?unread=true&page=1&page_size=10' \
  -H "Authorization: Bearer $BYTESPIKE_API_KEY"

​
Query parameters

ParamTypeNotes
unreadbooltrue to only return unread rows. Mutually exclusive with read.
readbooltrue to only return read rows.
typestringFilter by event type (see event catalog).
pageintegerDefault 1.
page_sizeintegerDefault 50, max 200.

​
Response

{
  "items": [
    {
      "id": 5001,
      "type": "system.payment.received",
      "title": "Payment received · $25.00",
      "body": "Your top-up has cleared. Available balance is now $31.40.",
      "link": "/billing",
      "read_at": null,
      "created_at": "2026-05-22T08:08:00Z"
    },
    {
      "id": 5006,
      "type": "system.payment.received",
      "title": "Payment received · $50.00",
      "body": "Stripe receipt #ch_3PYj-mock-49. Your balance is now $54.80.",
      "link": "/billing",
      "read_at": "2026-05-20T08:00:00Z",
      "created_at": "2026-05-20T05:08:00Z"
    }
  ],
  "total": 142,
  "page": 1,
  "page_size": 10
}

​
Response fields

FieldTypeNotes
items[].typestringOne of the 5 user-visible events (see event catalog).
items[].titlestringSingle-line summary shown in the bell dropdown.
items[].bodystringOne-paragraph description.
items[].linkstring | nullConsole-relative deep-link the row clicks through to.
items[].read_atstring | nullISO timestamp the user opened it. null = unread.
totalintegerMatches the filter (page-independent). When unread=true this is also the unread count.

​
Unread count

curl https://llm.bytespike.ai/api/v1/me/notifications/unread-count \
  -H "Authorization: Bearer $BYTESPIKE_API_KEY"

{"count": 7}
Cheaper than the list endpoint — use this for a badge that polls every minute or so.

​
Mark single read

curl -X POST https://llm.bytespike.ai/api/v1/me/notifications/5001/mark-read \
  -H "Authorization: Bearer $BYTESPIKE_API_KEY"

{
  "id": 5001,
  "type": "system.payment.received",
  "read_at": "2026-05-22T08:14:32Z"
}
Idempotent — calling it on an already-read row is a no-op (read_at unchanged).

​
Mark all read

curl -X POST https://llm.bytespike.ai/api/v1/me/notifications/mark-all-read \
  -H "Authorization: Bearer $BYTESPIKE_API_KEY"

{"marked_read": 7}
Returns the count flipped. Idempotent — calling again returns {"marked_read": 0}.

​
Event catalog

The notification feed only surfaces user-visible events — a curated subset of the webhook event catalog. Five types:
TypeWhen it fires
system.payment.receivedA top-up posts to your wallet
system.balance.notify.dispatchedLow-balance cron crossed your threshold
admin.org.member.addSomeone was added to your org (visible to org owners/admins)
admin.api_key.revokePlatform admin revoked your personal key
org.api_key.revokeOrg admin revoked one of your org keys
If you need the full set (every admin write, every org member change, etc.), use webhooks — those receive the wider catalog.

​
Errors

Statuserror.typeTrigger
400invalid_request_errorBoth read=true and unread=true, or unknown type.
401authentication_errorMissing / revoked key.
404not_found_errorNotification :id doesn’t belong to this caller.

​
Example — polling status bar

import time, requests, os

headers = {"Authorization": f"Bearer {os.environ['BYTESPIKE_API_KEY']}"}

while True:
    r = requests.get(
        "https://llm.bytespike.ai/api/v1/me/notifications/unread-count",
        headers=headers,
        timeout=5,
    ).json()
    print(f"Unread: {r['count']}")
    time.sleep(60)
Switch to a webhook subscription if you have an HTTPS endpoint — push beats polling on freshness and load.