Notifications & Events

DeveloperUpdated 9 July 2026

Overview

Everything that happens in your tenant — spaces created, collections changed, security-relevant actions, system events — lands in an append-only event log. On top of it, each user gets notifications for the events that concern them. Both are queryable over the API: events for audit and compliance tooling, notifications for building inbox-style UX.

Both APIs use the same cursor-based pagination (limit up to 100 per page, next_cursor/has_more in the meta object) and are scoped to the caller's tenant. Throughout, $BASE is your per-tenant gateway base — https://<your-tenant>.aimable.ai/api — and $KEY a credential with the permission named per endpoint.

The event log

Requires the events.read permission.

bash

curl "$BASE/v1/events?category=security&limit=50" \
  -H "X-API-Key: $KEY"

Parameter	Type	Meaning
`limit`	int (1–100, default 20)	Page size.
`cursor`	string	Keyset cursor from the previous page's `meta.next_cursor`.
`category`	string	One of `space`, `collection`, `security`, `system`.
`resource_type`	string	Filter by affected resource type (e.g. `space`, `collection`).
`resource_id`	uuid	Filter to one specific resource.
`from_date` / `to_date`	datetime	Inclusive time window on `created_at`.

Each event carries who did what to which resource:

json

{
  "data": [
    {
      "id": "550e8400-…",
      "category": "space",
      "event_type": "space.created",
      "actor_id": "550e8400-…",
      "actor_name": "Jane Doe",
      "actor_email": "jane@example.com",
      "resource_type": "space",
      "resource_id": "550e8400-…",
      "metadata": { "space_name": "Engineering" },
      "created_at": "2026-07-01T10:15:00+00:00"
    }
  ],
  "meta": { "next_cursor": "…", "has_more": true },
  "counts": { "space": 42, "collection": 5, "security": 2, "system": 10, "all": 59 }
}

The counts object gives per-category totals across your other filters — handy for tab counters that stay stable while the user switches categories. GET /v1/events/{event_id} fetches a single event. Events are immutable and ordered newest-first.

Tip: the same log is browsable in the Console under Event Log — see Observability & audit. Use the API when you need to feed a SIEM or compliance archive.

Notifications

Requires the notifications.read permission. Notifications are per-user: you only ever see your own.

Method & path	What it does
`GET /v1/notifications`	List (params: `limit`, `cursor`, `category`, `unread_only`).
`GET /v1/notifications/unread-count`	`{ "data": { "count": 5 } }` — for badge counters.
`GET /v1/notifications/{id}`	One notification.
`POST /v1/notifications/{id}/read`	Mark read (idempotent; returns the `read_at` timestamp).
`POST /v1/notifications/read-all`	Mark everything read; returns `marked_count`.

A notification references its underlying event and adds presentation fields:

json

{
  "id": "550e8400-…",
  "event_id": "550e8400-…",
  "title": "Space created",
  "body": "New space 'Engineering' was created",
  "category": "space",
  "resource_type": "space",
  "resource_id": "550e8400-…",
  "read_at": null,
  "created_at": "2026-07-01T10:15:00+00:00"
}

read_at: null means unread. A typical inbox integration polls unread-count, lists with unread_only=true, and calls …/read as the user opens items.

Reference

The full parameter and schema details live in the API Reference: the notifications and events groups.