notifications — SpiderIQ

GET/api/v1/notifications/preferences

Get Notification Preferences

Return the per-(user, brand) subscription matrix, grouped by section.

Sections + events come from the in-process catalog (1.1's services.notifications.catalog.CATALOG); per-event values are the user's overrides where set, otherwise the catalog defaults.

Parameters

Name	In	Type	Required	Description
`brand_id`	query	integer	true	Brand to load preferences for

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/notifications/preferences' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/notifications/preferences",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/notifications/preferences", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/notifications/preferences", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

PATCH/api/v1/notifications/preferences

Patch Notification Preferences

Bulk UPSERT partial overrides for one (user, brand).

Request body: {"updates": [ {"event_key": "campaign.terminal", "email": false}, {"event_key": "job.failed", "delivery": "digest-daily"} ]}

Fields absent from a per-event update preserve the existing row's value (or fall back to the catalog default if no row exists yet). standalone_only=True events force delivery='standalone' even if the caller sends another value — the catalog wins.

Unknown event_key or invalid delivery → 400. Non-member brand → 403.

Parameters

Name	In	Type	Required	Description
`brand_id`	query	integer	true	Brand the preferences apply to

Try it

Examples

cURL

curl -X PATCH 'https://spideriq.ai/api/v1/notifications/preferences' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "updates": [
    {
      "event_key": "string",
      "email": true,
      "in_app": true,
      "delivery": "string"
    }
  ]
}'

Python

import httpx

resp = httpx.patch(
    "https://spideriq.ai/api/v1/notifications/preferences",
    headers={"Authorization": "Bearer <token>", "Content-Type": "application/json"},
    json={"updates": [{"event_key": "string", "email": true, "in_app": true, "delivery": "string"}]},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/notifications/preferences", {
  method: "PATCH",
  headers: { "Authorization": "Bearer <token>", "Content-Type": "application/json" },
  body: JSON.stringify({"updates": [{"event_key": "string", "email": true, "in_app": true, "delivery": "string"}]})
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{"updates": [{"event_key": "string", "email": true, "in_app": true, "delivery": "string"}]}`)
	req, _ := http.NewRequest("PATCH", "https://spideriq.ai/api/v1/notifications/preferences", body)
	req.Header.Set("Authorization", "Bearer <token>")
	req.Header.Set("Content-Type", "application/json")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/notifications/feed

Get Notification Feed

Return the bell dropdown payload for (user, brand).

The unread branch is always top-N most recent; the read branch is keyset-paginated by (created_at, id) for the rare case the user scrolls past 20.

Parameters

Name	In	Type	Required	Description
`brand_id`	query	integer	true	Brand to load the bell feed for
`unread_only`	query	boolean	false	Skip the read mix
`unread_limit`	query	integer	false	Cap on unread rows returned
`read_limit`	query	integer	false	Cap on read rows returned (0 disables)
`before_created_at`	query	any	false	Keyset cursor (created_at half) — pass the last read row's created_at to page deeper
`before_id`	query	any	false	Keyset cursor (id half) — pass alongside before_created_at

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/notifications/feed' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/notifications/feed",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/notifications/feed", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/notifications/feed", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

GET/api/v1/notifications/unread-count

Get Notification Unread Count

Single-number response for the bell badge.

Parameters

Name	In	Type	Required	Description
`brand_id`	query	integer	true	Brand to count unread for

Try it

Examples

cURL

curl -X GET 'https://spideriq.ai/api/v1/notifications/unread-count' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.get(
    "https://spideriq.ai/api/v1/notifications/unread-count",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/notifications/unread-count", {
  method: "GET",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://spideriq.ai/api/v1/notifications/unread-count", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/notifications/{notification_id}/read

Mark Notification Read

Flip read_at on one row. Idempotent: re-marking a read row is a no-op (the COALESCE in feed_service keeps the original timestamp). 404 if the row doesn't exist OR doesn't belong to (user, brand) — same response shape for both because we never reveal which.

Parameters

Name	In	Type	Required	Description
`notification_id`	path	integer	true
`brand_id`	query	integer	true	Brand the notification belongs to
`created_at`	query	string	true	Row's created_at (from the feed response) — required for partition pruning on the partitioned notification_log

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/notifications/{notification_id}/read' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/notifications/{notification_id}/read",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/notifications/{notification_id}/read", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/notifications/{notification_id}/read", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error

POST/api/v1/notifications/read-all

Mark All Notifications Read

Bulk-clear unread for (user, brand). Returns the count flipped.

Parameters

Name	In	Type	Required	Description
`brand_id`	query	integer	true	Brand to clear unread for

Try it

Examples

cURL

curl -X POST 'https://spideriq.ai/api/v1/notifications/read-all' \
  -H 'Authorization: Bearer <token>'

Python

import httpx

resp = httpx.post(
    "https://spideriq.ai/api/v1/notifications/read-all",
    headers={"Authorization": "Bearer <token>"},
)
resp.raise_for_status()
print(resp.json())

JavaScript

const resp = await fetch("https://spideriq.ai/api/v1/notifications/read-all", {
  method: "POST",
  headers: { "Authorization": "Bearer <token>" }
});
const data = await resp.json();
console.log(data);

Go

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://spideriq.ai/api/v1/notifications/read-all", nil)
	req.Header.Set("Authorization", "Bearer <token>")
	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

Status	Description
`200`	Successful Response
`422`	Validation Error