iblai-api-notification

iblai-api-notification

Read and send an organization's platform notifications via the API: the unread count, the notifications list with channel/status/tag filters, mark-as-read (all, bulk, or specific), delete, and the two-step notification builder (preview then send/schedule, with source validation and recipient preview). Also manage a user's notification preferences, per-user push-device (FCM) tokens and, for org admins, the email templates and SMTP config that back notifications.

Auth & conventions

• Base URL: https://api.iblai.app
• Header: Authorization: Api-Token $IBLAI_API_KEY on every request.
• Path vars: {org} = $IBLAI_ORG, {username} = $IBLAI_USERNAME, {platform_key} = the org/platform key (usually $IBLAI_ORG), {type} = a notification-type key (e.g. USER_NOTIF_COURSE_ENROLLMENT), {build_id} = the id returned by the builder's preview/ step.
• These are platform-level endpoints on the DM host; all paths below sit under https://api.iblai.app/dm/api/notification/v1/ (written … in this doc).
• Not connected yet? Run /iblai-api-login first to populate IBLAI_ORG, IBLAI_USERNAME, and IBLAI_API_KEY.

Concepts

• Two-step builder. Sending a custom notification is preview/ → send/. preview/ resolves recipients and returns a build_id; send/ takes that build_id to actually send (or schedule, when preview/ was given a process_on datetime). validate_source/ and {build_id}/recipients/ let you check recipients before committing.
• Source types. A builder source is { "type": …, "data": … }. Valid type values: email, username, platform, csv, department, pathway, program, usergroup. data is a list of identifiers (or, for csv, an uploaded file — send validate_source/ as multipart).
• Templates: platform toggle vs. per-user preference. A template is a platform-admin object per notification {type} (its subject/body/channels), and templates/{type}/toggle/ enables or disables that type for the whole org. Separately, notification preferences are per-user (email/push on/off, frequency, per-type opt-outs). Both are distinct from marking messages read.
• Template inheritance. Each template reports is_inherited (using the main platform default vs. an org override), source_platform, and can_customize.

Reads

Notifications

• GET …/orgs/{org}/users/{username}/notifications-count/?status=UNREAD — unread count (filters: status, channel).
• GET …/orgs/{org}/users/{username}/notifications/ — notifications list. Filters: status, channel, exclude_channel, start_date, end_date, tags (comma-separated, matches ANY). Paginated. Each item: id, title, body, short_message, status, channel, context, tags, created_at, updated_at.

Notification builder

• GET …/orgs/{org}/notification-builder/context/ — context data for building: available templates, channels (with ids), and platforms.
• GET …/orgs/{org}/notification-builder/{build_id}/recipients/?search={q}&page={n}&page_size={n} — paged recipient preview for a built notification (search matches username/email).

Templates (org admin)

• GET …/platforms/{platform_key}/templates/ — list notification templates. Query: tags (comma-separated), page, page_size (default 25; passing page paginates). Each item: id, type, name, description, is_inherited, source_platform, is_enabled, can_customize, is_custom, message_title, email_subject, tags, spas, allowed_channels, available_context.
• GET …/platforms/{platform_key}/templates/{type}/ — one template's full detail (all editable content + per-type config + available_context).
• GET …/platforms/{platform_key}/templates/tags/ — the distinct tag values across the platform's templates (the lookup behind the tags filter on the list endpoint).

Notification preferences (per user)

• GET …/platforms/{platform_key}/notification-preferences/?username={username} — a user's preferences: email_enabled, push_enabled, notification_frequency, and type_preferences (read-only per-type map). username is optional (admin only); defaults to the caller.
• GET …/platforms/{platform_key}/notification-preferences/available-types/?username={username}&tags={csv} — notification types available on the platform, each with type, name, description, tags, is_enabled, user_preference.

Writes

Notifications

• PUT …/orgs/{org}/users/{username}/notifications/ — mark specific notifications read/unread: { "notification_id": "uuid", "status": "READ|UNREAD" }.
• POST …/orgs/{org}/mark-all-as-read — Confirm with the user first. Mark the caller's unread notifications read; returns { message, count }:

  { "notification_ids": "uuid[] (omit/empty = mark ALL unread)" }
  

• PATCH …/orgs/{org}/users/{username}/notifications/bulk-update/ — Confirm with the user first. Set every one of a user's notifications to one status: { "status": "READ|UNREAD" }. (RBAC: Ibl.Notifications/Notification/write.)
• DELETE …/orgs/{org}/users/{username}/notifications/{notification_id}/ — Confirm with the user first. Delete a single notification. (RBAC: Ibl.Notifications/Notification/delete.)

Notification builder

• POST …/orgs/{org}/notification-builder/validate_source/ — validate one recipient source before building. Body { "type": …, "data": … } (multipart with a data file for csv) → { status, valid_count, invalid_entries[], sample_recipients[] }.
• POST …/orgs/{org}/notification-builder/preview/ — builder step 1; resolves recipients and returns { status, build_id, count, warning, recipients[] }. Body: see Schema.
• POST …/orgs/{org}/notification-builder/send/ — Confirm with the user first. Step 2, send/schedule the built notification: { "build_id": "string (required)" } → { status, notifications_sent, build_id, message }.

Templates (org admin)

• PATCH …/platforms/{platform_key}/templates/{type}/ — edit a template's content and config (see Schema).
• PATCH …/platforms/{platform_key}/templates/{type}/toggle/ — enable/disable this type for the org: { "allow_notification": bool (required) }.
• POST …/platforms/{platform_key}/templates/{type}/reset/ — reset the template to its platform default (no body).
• POST …/platforms/{platform_key}/templates/{type}/test/ — Confirm with the user first. Send a test render to the caller: { "context": {…}, "use_sample_context": bool } (both optional; use_sample_context defaults true) → { success, message, recipient }.

Notification preferences (per user)

• PATCH …/platforms/{platform_key}/notification-preferences/?username={username} — update a user's preferences: { "email_enabled": bool, "push_enabled": bool, "notification_frequency": "string" }.
• PATCH …/platforms/{platform_key}/notification-preferences/types/{type}/?username={username} — enable/disable one type for the user: { "enabled": bool }.

SMTP (org admin)

• POST …/platforms/{platform_key}/config/test-smtp/ — Confirm with the user first. Send a test email to verify SMTP: { smtp_host, smtp_port, smtp_username, smtp_password, use_tls (default true), use_ssl (default false), test_email, from_email (optional) } → { status, message, success }.

Push devices (FCM)

• POST …/orgs/{org}/users/{username}/register-fcm-token/ — register a push device: { "registration_id": "string (required)", "name": "string" }.
• DELETE …/orgs/{org}/users/{username}/register-fcm-token/ — Confirm with the user first. Unregister a push device: { "registration_id": "string" }.

Schema

Builder preview/ body (Mode: req=required, opt=optional):

Field	Type	Mode	Notes
channels	integer[]	req	Channel ids (from …/notification-builder/context/).
sources	object[]	req	Each { "type": <source type>, "data": … }.
template_id	uuid	opt	Use a predefined template. Mutually exclusive with template_data.
template_data	object	opt	Ad-hoc message: { "message_title": str (opt), "message_body": str (req) }.
context	object	opt	Extra variables available in the message text.
process_on	ISO datetime	opt	Schedule; sent hourly, only if before the hour boundary.

Template PATCH body — editable content fields: message_title, message_body, short_message_body, email_subject, email_from_address, email_html_template, tags, spa_ids, channel_ids. Advanced templates also accept per-type config inputs (verified in the template detail serializer), e.g. periodic_* (report cadence), policy_*, recipients_*, human_support_*, new_content_*, course_milestone_*, skill_mastery_*, schedule_change_*, courses_progress_*, grade_posted_*. Fields like is_inherited, is_enabled, source_platform, can_customize, available_context, and the *_config objects are read-only.

Example

Check the unread notification count for the current user:

curl -s \
  "https://api.iblai.app/dm/api/notification/v1/orgs/$IBLAI_ORG/users/$IBLAI_USERNAME/notifications-count/?status=UNREAD" \
  -H "Authorization: Api-Token $IBLAI_API_KEY"

Notes

• Sending a notification is outward-facing — confirm recipients with the user before the send/ step (and before templates/{type}/test/ and config/test-smtp/, which both send real email).
• The builder is two steps: preview/ returns a build_id, then send/ takes that build_id to actually send or schedule. A process_on passed to preview/ turns the send into a scheduled one.
• mark-all-as-read with an empty/omitted notification_ids marks all the caller's unread notifications read; pass ids to mark just those. bulk-update differs: it sets every notification for a target user to one status (and can move them back to UNREAD).
• Template toggle/ (platform-wide on/off for a type) is different from per-user notification-preferences/ — don't confuse the two.

Reference material

Doc-sourced companions to the endpoints above (concepts and catalogs — the API surface itself stays here in SKILL.md):

• references/guide.md — how notifications are generated (automatic vs the direct-send builder, with the builder flow, source types, and duplicate detection), SMTP/FCM channel setup, permissions/RBAC, the delivery/read lifecycle, and gotchas.
• references/templates.md — the notification-type catalog, template-inheritance semantics, the template-variable and HTML-sanitization reference, and the three system-managed types (human support, policy assignment, proactive-learner AI) with their per-type config.