notifications

Notifications

Templates, preferences, send/retry, provider credentials, push device registration, and usage.

34 נקודות קצה

GET /api/v1/me/notifications

The caller’s own in-app notification inbox, newest first (cursor-paginated).

דורש אימותהרשאהללא הרשאה נוספת

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
cursor
querystring—
limit
queryinteger1–100 · default: 25
unreadOnly
queryenum: "true" | "false"default: "false"

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/me/notifications" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "templateKey": "string",
      "locale": "ar",
      "title": "Midterm Exam",
      "body": "string",
      "payload": {},
      "readAt": "2026-03-02T09:00:00.000Z",
      "createdAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/me/notifications/{id}/read

Mark one of the caller’s own inbox entries as read (idempotent).

דורש אימותהרשאהללא הרשאה נוספת

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/me/notifications/37386ae0-3738-7738-8386-37386ae03738/read" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
okחובה
enum: true—
updatedחובה
integer0–9007199254740991
json
{
  "ok": true,
  "updated": 0
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/me/notifications/read-all

Mark every unread inbox entry of the caller’s own as read.

דורש אימותהרשאהללא הרשאה נוספת

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/me/notifications/read-all" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
okחובה
enum: true—
updatedחובה
integer0–9007199254740991
json
{
  "ok": true,
  "updated": 0
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/me/notifications/unread-count

How many of the caller’s own inbox entries are still unread.

דורש אימותהרשאהללא הרשאה נוספת

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/me/notifications/unread-count" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
unreadחובה
integer0–9007199254740991
json
{
  "unread": 0
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/notification-preferences

The caller's own per-channel notification preferences.

דורש אימותהרשאהללא הרשאה נוספת

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/notification-preferences" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
preferencesחובה
array<object>—
json
{
  "preferences": [
    {
      "channel": "push",
      "enabled": true,
      "digestMode": "immediate"
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

PUT /api/v1/notification-preferences

Sets one or more of the caller's own per-channel notification preferences.

דורש אימותהרשאהללא הרשאה נוספת

גוף הבקשה

שםסוגמגבלות
preferencesחובה
array<object>—

דוגמה

json
{
  "preferences": [
    {
      "channel": "push",
      "enabled": true,
      "digestMode": "immediate"
    }
  ]
}

דוגמה עם curl

curl
curl -X PUT "https://your-institute.example/api/v1/notification-preferences" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "preferences": [
      {
        "channel": "push",
        "enabled": true,
        "digestMode": "immediate"
      }
    ]
  }'

תשובות

200
שםסוגמגבלות
preferencesחובה
array<object>—
json
{
  "preferences": [
    {
      "channel": "push",
      "enabled": true,
      "digestMode": "immediate"
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/notification-rules

The effective rule of every notification type, in the registry order, cursor-paginated (the whole catalogue fits one page). Each entry carries what the type allows, its locks, the Institflow default and the version to echo as `expectedVersion`.

דורש אימותהרשאהnotifications.read

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
cursor
querystring—
limit
queryinteger1–100 · default: 25

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/notification-rules" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "typeKey": "string",
      "category": "attendance",
      "trigger": {
        "kind": "event",
        "event": "string",
        "anchor": "string"
      },
      "subject": "string",
      "recipientKinds": [
        "students"
      ],
      "staffPermission": "string",
      "defaultStaffAudience": "none",
      "scopes": [
        "course"
      ],
      "guardianGrouping": "per_child",
      "urgencyChoice": true,
      "locks": {
        "enabled": true,
        "minimumStaff": true,
        "userCanMute": true,
        "emailOn": true
      },
      "reminder": {
        "maxLeads": -9007199254740991,
        "supportsItemMode": true,
        "supportsEnrolmentRelative": true
      },
      "legacySettingKey": "string",
      "rule": {
        "enabled": true,
        "students": true,
        "teachers": true,
        "guardians": "none",
        "staff": {
          "mode": "default",
          "roleIds": [
            "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
          ]
        },
        "memberIds": [
          "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
        ],
        "channels": {
          "push": true,
          "email": "ada.lovelace@example.com",
          "sms": true,
          "whatsapp": true
        },
        "urgency": "immediate",
        "reminder": {
          "leads": [
            "value"
          ],
          "respectQuietHours": true,
          "includeEnrolmentRelative": true
        },
        "scope": {
          "mode": "all",
          "courseIds": [
            "8e692f22-8e69-7e69-8692-8e692f228e69"
          ],
          "groupIds": [
            "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
          ]
        },
        "userCanMute": true
      },
      "defaults": {
        "enabled": true,
        "students": true,
        "teachers": true,
        "guardians": "none",
        "staff": {
          "mode": "default",
          "roleIds": [
            "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
          ]
        },
        "memberIds": [
          "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
        ],
        "channels": {
          "push": true,
          "email": "ada.lovelace@example.com",
          "sms": true,
          "whatsapp": true
        },
        "urgency": "immediate",
        "reminder": {
          "leads": [
            "value"
          ],
          "respectQuietHours": true,
          "includeEnrolmentRelative": true
        },
        "scope": {
          "mode": "all",
          "courseIds": [
            "8e692f22-8e69-7e69-8692-8e692f228e69"
          ],
          "groupIds": [
            "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
          ]
        },
        "userCanMute": true
      },
      "customisedFields": [
        "string"
      ],
      "version": -9007199254740991,
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/notification-rules/{typeKey}

One type: the effective rule, the institute's own override, the locks and — per channel — whether it can deliver, who bills it and at what price.

דורש אימותהרשאהnotifications.read

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
typeKeyחובה
pathstring—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/notification-rules/string" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
typeKeyחובה
string—
categoryחובה
enum: "attendance" | "billing" | "learning" | "reminders" | "institute"—
triggerחובה
object—
subjectחובה
string—
recipientKindsחובה
array<enum: "students" | "guardians" | "teachers" | "staff" | "members">—
staffPermissionחובה
string | null—
defaultStaffAudienceחובה
enum: "none" | "permission_holders" | "owners_managers"—
scopesחובה
array<enum: "course" | "group">—
guardianGroupingחובה
enum: "per_child" | "per_subject"—
urgencyChoiceחובה
boolean—
locksחובה
object—
reminderחובה
object | null—
legacySettingKeyחובה
string | null—
ruleחובה
object—
defaultsחובה
object—
customisedFieldsחובה
array<string>—
versionחובה
integer-9007199254740991–9007199254740991
updatedAtחובה
string (date-time) | null—
overrideחובה
object | null—
channelStatesחובה
array<object>—
json
{
  "typeKey": "string",
  "category": "attendance",
  "trigger": {
    "kind": "event",
    "event": "string",
    "anchor": "string"
  },
  "subject": "string",
  "recipientKinds": [
    "students"
  ],
  "staffPermission": "string",
  "defaultStaffAudience": "none",
  "scopes": [
    "course"
  ],
  "guardianGrouping": "per_child",
  "urgencyChoice": true,
  "locks": {
    "enabled": true,
    "minimumStaff": true,
    "userCanMute": true,
    "emailOn": true
  },
  "reminder": {
    "maxLeads": -9007199254740991,
    "supportsItemMode": true,
    "supportsEnrolmentRelative": true
  },
  "legacySettingKey": "string",
  "rule": {
    "enabled": true,
    "students": true,
    "teachers": true,
    "guardians": "none",
    "staff": {
      "mode": "default",
      "roleIds": [
        "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
      ]
    },
    "memberIds": [
      "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
    ],
    "channels": {
      "push": true,
      "email": "ada.lovelace@example.com",
      "sms": true,
      "whatsapp": true
    },
    "urgency": "immediate",
    "reminder": {
      "leads": [
        "value"
      ],
      "respectQuietHours": true,
      "includeEnrolmentRelative": true
    },
    "scope": {
      "mode": "all",
      "courseIds": [
        "8e692f22-8e69-7e69-8692-8e692f228e69"
      ],
      "groupIds": [
        "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
      ]
    },
    "userCanMute": true
  },
  "defaults": {
    "enabled": true,
    "students": true,
    "teachers": true,
    "guardians": "none",
    "staff": {
      "mode": "default",
      "roleIds": [
        "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
      ]
    },
    "memberIds": [
      "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
    ],
    "channels": {
      "push": true,
      "email": "ada.lovelace@example.com",
      "sms": true,
      "whatsapp": true
    },
    "urgency": "immediate",
    "reminder": {
      "leads": [
        "value"
      ],
      "respectQuietHours": true,
      "includeEnrolmentRelative": true
    },
    "scope": {
      "mode": "all",
      "courseIds": [
        "8e692f22-8e69-7e69-8692-8e692f228e69"
      ],
      "groupIds": [
        "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
      ]
    },
    "userCanMute": true
  },
  "customisedFields": [
    "string"
  ],
  "version": -9007199254740991,
  "updatedAt": "2026-03-02T09:00:00.000Z",
  "override": {
    "enabled": true,
    "students": true,
    "teachers": true,
    "guardians": "none",
    "staff": {
      "mode": "default",
      "roleIds": [
        "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
      ]
    },
    "memberIds": [
      "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
    ],
    "channels": {
      "push": true,
      "email": "ada.lovelace@example.com",
      "sms": true,
      "whatsapp": true
    },
    "urgency": "immediate",
    "reminder": {
      "leads": [
        "value"
      ],
      "respectQuietHours": true,
      "includeEnrolmentRelative": true
    },
    "scope": {
      "mode": "all",
      "courseIds": [
        "8e692f22-8e69-7e69-8692-8e692f228e69"
      ],
      "groupIds": [
        "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
      ]
    },
    "userCanMute": true
  },
  "channelStates": [
    {
      "channel": "push",
      "status": "own",
      "reason": "Requested by guardian.",
      "deliverable": true,
      "billing": "free",
      "unitPriceUnits": -9007199254740991
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

PUT /api/v1/notification-rules/{typeKey}

Replaces the institute's override of one type (a field left out is the Institflow default again). `expectedVersion` guards against a concurrent edit (409 `VERSION_CONFLICT`). A change that raises what the institute pays for — a paid channel switched on, recipients, lead times or scope added to a type with a paid channel — is refused with 422 `VALIDATION_ERROR` and `details.reason = "cost_confirmation_required"` plus the estimate, unless `confirmCost` is `true`. A channel this install cannot deliver cannot be switched on (403 `FEATURE_DISABLED`).

דורש אימותהרשאהnotifications.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
typeKeyחובה
pathstring—

גוף הבקשה

שםסוגמגבלות
ruleחובה
object—
expectedVersion
integer0–9007199254740991
confirmCost
boolean—

דוגמה

json
{
  "rule": {
    "enabled": true,
    "students": true,
    "teachers": true,
    "guardians": "none",
    "staff": {
      "mode": "default",
      "roleIds": [
        "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
      ]
    },
    "memberIds": [
      "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
    ],
    "channels": {
      "push": true,
      "email": "ada.lovelace@example.com",
      "sms": true,
      "whatsapp": true
    },
    "urgency": "immediate",
    "reminder": {
      "leads": [
        "value"
      ],
      "respectQuietHours": true,
      "includeEnrolmentRelative": true
    },
    "scope": {
      "mode": "all",
      "courseIds": [
        "8e692f22-8e69-7e69-8692-8e692f228e69"
      ],
      "groupIds": [
        "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
      ]
    },
    "userCanMute": true
  },
  "expectedVersion": 0,
  "confirmCost": true
}

דוגמה עם curl

curl
curl -X PUT "https://your-institute.example/api/v1/notification-rules/string" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "rule": {
      "enabled": true,
      "students": true,
      "teachers": true,
      "guardians": "none",
      "staff": {
        "mode": "default",
        "roleIds": [
          "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
        ]
      },
      "memberIds": [
        "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
      ],
      "channels": {
        "push": true,
        "email": "ada.lovelace@example.com",
        "sms": true,
        "whatsapp": true
      },
      "urgency": "immediate",
      "reminder": {
        "leads": [
          "value"
        ],
        "respectQuietHours": true,
        "includeEnrolmentRelative": true
      },
      "scope": {
        "mode": "all",
        "courseIds": [
          "8e692f22-8e69-7e69-8692-8e692f228e69"
        ],
        "groupIds": [
          "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
        ]
      },
      "userCanMute": true
    },
    "expectedVersion": 0,
    "confirmCost": true
  }'

תשובות

200
שםסוגמגבלות
typeKeyחובה
string—
categoryחובה
enum: "attendance" | "billing" | "learning" | "reminders" | "institute"—
triggerחובה
object—
subjectחובה
string—
recipientKindsחובה
array<enum: "students" | "guardians" | "teachers" | "staff" | "members">—
staffPermissionחובה
string | null—
defaultStaffAudienceחובה
enum: "none" | "permission_holders" | "owners_managers"—
scopesחובה
array<enum: "course" | "group">—
guardianGroupingחובה
enum: "per_child" | "per_subject"—
urgencyChoiceחובה
boolean—
locksחובה
object—
reminderחובה
object | null—
legacySettingKeyחובה
string | null—
ruleחובה
object—
defaultsחובה
object—
customisedFieldsחובה
array<string>—
versionחובה
integer-9007199254740991–9007199254740991
updatedAtחובה
string (date-time) | null—
overrideחובה
object | null—
channelStatesחובה
array<object>—
json
{
  "typeKey": "string",
  "category": "attendance",
  "trigger": {
    "kind": "event",
    "event": "string",
    "anchor": "string"
  },
  "subject": "string",
  "recipientKinds": [
    "students"
  ],
  "staffPermission": "string",
  "defaultStaffAudience": "none",
  "scopes": [
    "course"
  ],
  "guardianGrouping": "per_child",
  "urgencyChoice": true,
  "locks": {
    "enabled": true,
    "minimumStaff": true,
    "userCanMute": true,
    "emailOn": true
  },
  "reminder": {
    "maxLeads": -9007199254740991,
    "supportsItemMode": true,
    "supportsEnrolmentRelative": true
  },
  "legacySettingKey": "string",
  "rule": {
    "enabled": true,
    "students": true,
    "teachers": true,
    "guardians": "none",
    "staff": {
      "mode": "default",
      "roleIds": [
        "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
      ]
    },
    "memberIds": [
      "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
    ],
    "channels": {
      "push": true,
      "email": "ada.lovelace@example.com",
      "sms": true,
      "whatsapp": true
    },
    "urgency": "immediate",
    "reminder": {
      "leads": [
        "value"
      ],
      "respectQuietHours": true,
      "includeEnrolmentRelative": true
    },
    "scope": {
      "mode": "all",
      "courseIds": [
        "8e692f22-8e69-7e69-8692-8e692f228e69"
      ],
      "groupIds": [
        "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
      ]
    },
    "userCanMute": true
  },
  "defaults": {
    "enabled": true,
    "students": true,
    "teachers": true,
    "guardians": "none",
    "staff": {
      "mode": "default",
      "roleIds": [
        "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
      ]
    },
    "memberIds": [
      "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
    ],
    "channels": {
      "push": true,
      "email": "ada.lovelace@example.com",
      "sms": true,
      "whatsapp": true
    },
    "urgency": "immediate",
    "reminder": {
      "leads": [
        "value"
      ],
      "respectQuietHours": true,
      "includeEnrolmentRelative": true
    },
    "scope": {
      "mode": "all",
      "courseIds": [
        "8e692f22-8e69-7e69-8692-8e692f228e69"
      ],
      "groupIds": [
        "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
      ]
    },
    "userCanMute": true
  },
  "customisedFields": [
    "string"
  ],
  "version": -9007199254740991,
  "updatedAt": "2026-03-02T09:00:00.000Z",
  "override": {
    "enabled": true,
    "students": true,
    "teachers": true,
    "guardians": "none",
    "staff": {
      "mode": "default",
      "roleIds": [
        "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
      ]
    },
    "memberIds": [
      "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
    ],
    "channels": {
      "push": true,
      "email": "ada.lovelace@example.com",
      "sms": true,
      "whatsapp": true
    },
    "urgency": "immediate",
    "reminder": {
      "leads": [
        "value"
      ],
      "respectQuietHours": true,
      "includeEnrolmentRelative": true
    },
    "scope": {
      "mode": "all",
      "courseIds": [
        "8e692f22-8e69-7e69-8692-8e692f228e69"
      ],
      "groupIds": [
        "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
      ]
    },
    "userCanMute": true
  },
  "channelStates": [
    {
      "channel": "push",
      "status": "own",
      "reason": "Requested by guardian.",
      "deliverable": true,
      "billing": "free",
      "unitPriceUnits": -9007199254740991
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/notification-rules/{typeKey}/preview

Changes nothing: the monthly cost estimate (a range, in credit units), how many people the rule would reach by kind, whether saving it needs `confirmCost`, and warnings. Without a body it describes the current rule.

דורש אימותהרשאהnotifications.read

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
typeKeyחובה
pathstring—

גוף הבקשה

שםסוגמגבלות
rule
object—

דוגמה

json
{
  "rule": {
    "enabled": true,
    "students": true,
    "teachers": true,
    "guardians": "none",
    "staff": {
      "mode": "default",
      "roleIds": [
        "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
      ]
    },
    "memberIds": [
      "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
    ],
    "channels": {
      "push": true,
      "email": "ada.lovelace@example.com",
      "sms": true,
      "whatsapp": true
    },
    "urgency": "immediate",
    "reminder": {
      "leads": [
        "value"
      ],
      "respectQuietHours": true,
      "includeEnrolmentRelative": true
    },
    "scope": {
      "mode": "all",
      "courseIds": [
        "8e692f22-8e69-7e69-8692-8e692f228e69"
      ],
      "groupIds": [
        "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
      ]
    },
    "userCanMute": true
  }
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/notification-rules/string/preview" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "rule": {
      "enabled": true,
      "students": true,
      "teachers": true,
      "guardians": "none",
      "staff": {
        "mode": "default",
        "roleIds": [
          "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
        ]
      },
      "memberIds": [
        "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
      ],
      "channels": {
        "push": true,
        "email": "ada.lovelace@example.com",
        "sms": true,
        "whatsapp": true
      },
      "urgency": "immediate",
      "reminder": {
        "leads": [
          "value"
        ],
        "respectQuietHours": true,
        "includeEnrolmentRelative": true
      },
      "scope": {
        "mode": "all",
        "courseIds": [
          "8e692f22-8e69-7e69-8692-8e692f228e69"
        ],
        "groupIds": [
          "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
        ]
      },
      "userCanMute": true
    }
  }'

תשובות

200
שםסוגמגבלות
effectiveחובה
object—
requiresCostConfirmationחובה
boolean—
estimateחובה
object—
recipientsחובה
object—
warningsחובה
array<object>—
json
{
  "effective": {
    "enabled": true,
    "students": true,
    "teachers": true,
    "guardians": "none",
    "staff": {
      "mode": "default",
      "roleIds": [
        "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
      ]
    },
    "memberIds": [
      "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
    ],
    "channels": {
      "push": true,
      "email": "ada.lovelace@example.com",
      "sms": true,
      "whatsapp": true
    },
    "urgency": "immediate",
    "reminder": {
      "leads": [
        "value"
      ],
      "respectQuietHours": true,
      "includeEnrolmentRelative": true
    },
    "scope": {
      "mode": "all",
      "courseIds": [
        "8e692f22-8e69-7e69-8692-8e692f228e69"
      ],
      "groupIds": [
        "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
      ]
    },
    "userCanMute": true
  },
  "requiresCostConfirmation": true,
  "estimate": {
    "basis": "history",
    "recipientsPerMonth": -9007199254740991,
    "channels": [
      {
        "channel": "push",
        "billing": "free",
        "messagesLow": -9007199254740991,
        "messagesHigh": -9007199254740991,
        "costLowUnits": -9007199254740991,
        "costHighUnits": -9007199254740991
      }
    ],
    "totalLowUnits": -9007199254740991,
    "totalHighUnits": -9007199254740991
  },
  "recipients": {
    "students": -9007199254740991,
    "guardians": -9007199254740991,
    "teachers": -9007199254740991,
    "staff": -9007199254740991,
    "members": -9007199254740991
  },
  "warnings": [
    {
      "code": "string",
      "detail": "string"
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/notification-rules/{typeKey}/reset

Deletes the override the institute made: the type goes back to the Institflow default. Going back can switch the type or a paid channel on again; that answers 422 with the estimate until the request carries `confirmCost: true`, exactly like a save.

דורש אימותהרשאהnotifications.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
typeKeyחובה
pathstring—

גוף הבקשה

שםסוגמגבלות
expectedVersion
integer0–9007199254740991
confirmCost
boolean—

דוגמה

json
{
  "expectedVersion": 0,
  "confirmCost": true
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/notification-rules/string/reset" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "expectedVersion": 0,
    "confirmCost": true
  }'

תשובות

200
שםסוגמגבלות
typeKeyחובה
string—
categoryחובה
enum: "attendance" | "billing" | "learning" | "reminders" | "institute"—
triggerחובה
object—
subjectחובה
string—
recipientKindsחובה
array<enum: "students" | "guardians" | "teachers" | "staff" | "members">—
staffPermissionחובה
string | null—
defaultStaffAudienceחובה
enum: "none" | "permission_holders" | "owners_managers"—
scopesחובה
array<enum: "course" | "group">—
guardianGroupingחובה
enum: "per_child" | "per_subject"—
urgencyChoiceחובה
boolean—
locksחובה
object—
reminderחובה
object | null—
legacySettingKeyחובה
string | null—
ruleחובה
object—
defaultsחובה
object—
customisedFieldsחובה
array<string>—
versionחובה
integer-9007199254740991–9007199254740991
updatedAtחובה
string (date-time) | null—
overrideחובה
object | null—
channelStatesחובה
array<object>—
json
{
  "typeKey": "string",
  "category": "attendance",
  "trigger": {
    "kind": "event",
    "event": "string",
    "anchor": "string"
  },
  "subject": "string",
  "recipientKinds": [
    "students"
  ],
  "staffPermission": "string",
  "defaultStaffAudience": "none",
  "scopes": [
    "course"
  ],
  "guardianGrouping": "per_child",
  "urgencyChoice": true,
  "locks": {
    "enabled": true,
    "minimumStaff": true,
    "userCanMute": true,
    "emailOn": true
  },
  "reminder": {
    "maxLeads": -9007199254740991,
    "supportsItemMode": true,
    "supportsEnrolmentRelative": true
  },
  "legacySettingKey": "string",
  "rule": {
    "enabled": true,
    "students": true,
    "teachers": true,
    "guardians": "none",
    "staff": {
      "mode": "default",
      "roleIds": [
        "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
      ]
    },
    "memberIds": [
      "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
    ],
    "channels": {
      "push": true,
      "email": "ada.lovelace@example.com",
      "sms": true,
      "whatsapp": true
    },
    "urgency": "immediate",
    "reminder": {
      "leads": [
        "value"
      ],
      "respectQuietHours": true,
      "includeEnrolmentRelative": true
    },
    "scope": {
      "mode": "all",
      "courseIds": [
        "8e692f22-8e69-7e69-8692-8e692f228e69"
      ],
      "groupIds": [
        "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
      ]
    },
    "userCanMute": true
  },
  "defaults": {
    "enabled": true,
    "students": true,
    "teachers": true,
    "guardians": "none",
    "staff": {
      "mode": "default",
      "roleIds": [
        "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
      ]
    },
    "memberIds": [
      "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
    ],
    "channels": {
      "push": true,
      "email": "ada.lovelace@example.com",
      "sms": true,
      "whatsapp": true
    },
    "urgency": "immediate",
    "reminder": {
      "leads": [
        "value"
      ],
      "respectQuietHours": true,
      "includeEnrolmentRelative": true
    },
    "scope": {
      "mode": "all",
      "courseIds": [
        "8e692f22-8e69-7e69-8692-8e692f228e69"
      ],
      "groupIds": [
        "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
      ]
    },
    "userCanMute": true
  },
  "customisedFields": [
    "string"
  ],
  "version": -9007199254740991,
  "updatedAt": "2026-03-02T09:00:00.000Z",
  "override": {
    "enabled": true,
    "students": true,
    "teachers": true,
    "guardians": "none",
    "staff": {
      "mode": "default",
      "roleIds": [
        "9ded041d-9ded-7ded-8ed0-9ded041d9ded"
      ]
    },
    "memberIds": [
      "b34e3ee7-b34e-734e-84e3-b34e3ee7b34e"
    ],
    "channels": {
      "push": true,
      "email": "ada.lovelace@example.com",
      "sms": true,
      "whatsapp": true
    },
    "urgency": "immediate",
    "reminder": {
      "leads": [
        "value"
      ],
      "respectQuietHours": true,
      "includeEnrolmentRelative": true
    },
    "scope": {
      "mode": "all",
      "courseIds": [
        "8e692f22-8e69-7e69-8692-8e692f228e69"
      ],
      "groupIds": [
        "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
      ]
    },
    "userCanMute": true
  },
  "channelStates": [
    {
      "channel": "push",
      "status": "own",
      "reason": "Requested by guardian.",
      "deliverable": true,
      "billing": "free",
      "unitPriceUnits": -9007199254740991
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/notification-spend

This month's notification usage per channel and, when the install is on the Institflow messaging relay, the credit balance and overdraft limit as last synced.

דורש אימותהרשאהnotifications.manage

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/notification-spend" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
periodחובה
string—
relayחובה
object | null—
usageחובה
array<object>—
json
{
  "period": "string",
  "relay": {
    "balanceUnits": -9007199254740991,
    "overdraftUnits": -9007199254740991,
    "status": "active"
  },
  "usage": [
    {
      "channel": "string",
      "count": -9007199254740991,
      "costMinor": -9007199254740991
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/notification-templates

Tenant overrides merged with platform defaults.

דורש אימותהרשאהnotifications.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
cursor
querystring—
limit
queryinteger1–100 · default: 25

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/notification-templates" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "key": "string",
      "channel": "push",
      "locale": "ar",
      "subject": "string",
      "body": "string",
      "providerTemplateName": "string",
      "isActive": true,
      "isPlatformDefault": true,
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/notification-templates

Creates a tenant override for a template key/channel/locale.

דורש אימותהרשאהnotifications.manage

גוף הבקשה

שםסוגמגבלות
keyחובה
string1–150 chars
channelחובה
enum: "push" | "whatsapp" | "email" | "sms" | "in_app"—
localeחובה
enum: "ar" | "en" | "he"—
subject
string1–300 chars
bodyחובה
string1–5000 chars
providerTemplateName
string1–150 chars
isActive
booleandefault: true

דוגמה

json
{
  "key": "string",
  "channel": "push",
  "locale": "ar",
  "subject": "string",
  "body": "string",
  "providerTemplateName": "string",
  "isActive": true
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/notification-templates" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "key": "string",
    "channel": "push",
    "locale": "ar",
    "subject": "string",
    "body": "string",
    "providerTemplateName": "string",
    "isActive": true
  }'

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
keyחובה
string—
channelחובה
enum: "push" | "whatsapp" | "email" | "sms" | "in_app"—
localeחובה
enum: "ar" | "en" | "he"—
subjectחובה
string | null≥1 chars
bodyחובה
string—
providerTemplateNameחובה
string | null≥1 chars
isActiveחובה
boolean—
isPlatformDefaultחובה
boolean—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "key": "string",
  "channel": "push",
  "locale": "ar",
  "subject": "string",
  "body": "string",
  "providerTemplateName": "string",
  "isActive": true,
  "isPlatformDefault": true,
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

DELETE /api/v1/notification-templates/{id}

Deletes a tenant override.

דורש אימותהרשאהnotifications.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

דוגמה עם curl

curl
curl -X DELETE "https://your-institute.example/api/v1/notification-templates/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

PATCH /api/v1/notification-templates/{id}

Updates a tenant override (never a platform default row).

דורש אימותהרשאהnotifications.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

גוף הבקשה

שםסוגמגבלות
subject
string1–300 chars
body
string1–5000 chars
providerTemplateName
string1–150 chars
isActive
booleandefault: true

דוגמה

json
{
  "subject": "string",
  "body": "string",
  "providerTemplateName": "string",
  "isActive": true
}

דוגמה עם curl

curl
curl -X PATCH "https://your-institute.example/api/v1/notification-templates/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "subject": "string",
    "body": "string",
    "providerTemplateName": "string",
    "isActive": true
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
keyחובה
string—
channelחובה
enum: "push" | "whatsapp" | "email" | "sms" | "in_app"—
localeחובה
enum: "ar" | "en" | "he"—
subjectחובה
string | null≥1 chars
bodyחובה
string—
providerTemplateNameחובה
string | null≥1 chars
isActiveחובה
boolean—
isPlatformDefaultחובה
boolean—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "key": "string",
  "channel": "push",
  "locale": "ar",
  "subject": "string",
  "body": "string",
  "providerTemplateName": "string",
  "isActive": true,
  "isPlatformDefault": true,
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/notification-templates/{id}/test

Renders this template against a fixed sample payload and sends it, through the tenant's real provider for its channel, to the calling user's own contact address. Never sends to anyone else.

דורש אימותהרשאהnotifications.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/notification-templates/37386ae0-3738-7738-8386-37386ae03738/test" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

201
שםסוגמגבלות
okחובה
enum: true—
sentToחובה
string—
channelחובה
enum: "push" | "whatsapp" | "email" | "sms" | "in_app"—
json
{
  "ok": true,
  "sentTo": "string",
  "channel": "push"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/notification-type-preferences

The caller's own per-type notification switches (class reminder, work-due reminder, new lesson). A type never switched off is on.

דורש אימותהרשאהללא הרשאה נוספת

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/notification-type-preferences" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
preferencesחובה
array<object>—
json
{
  "preferences": [
    {
      "typeKey": "student.absent",
      "enabled": true,
      "canMute": true
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

PUT /api/v1/notification-type-preferences

Switches one or more of the caller's own notification types on or off.

דורש אימותהרשאהללא הרשאה נוספת

גוף הבקשה

שםסוגמגבלות
preferencesחובה
array<object>—

דוגמה

json
{
  "preferences": [
    {
      "typeKey": "student.absent",
      "enabled": true
    }
  ]
}

דוגמה עם curl

curl
curl -X PUT "https://your-institute.example/api/v1/notification-type-preferences" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "preferences": [
      {
        "typeKey": "student.absent",
        "enabled": true
      }
    ]
  }'

תשובות

200
שםסוגמגבלות
preferencesחובה
array<object>—
json
{
  "preferences": [
    {
      "typeKey": "student.absent",
      "enabled": true,
      "canMute": true
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/notification-usage

Per-channel usage/cost counters for a billing period (default: the current month).

דורש אימותהרשאהnotifications.read

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/notification-usage" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
periodחובה
string—
usageחובה
array<object>—
json
{
  "period": "string",
  "usage": [
    {
      "channel": "push",
      "count": -9007199254740991,
      "costMinor": -9007199254740991
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/notifications

List the outbox log, cursor-paginated, filterable by status/channel/recipient.

דורש אימותהרשאהnotifications.read

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
cursor
querystring—
limit
queryinteger1–100 · default: 25
status
queryenum: "queued" | "sending" | "sent" | "delivered" | "failed" | "skipped"—
channel
queryenum: "push" | "whatsapp" | "email" | "sms" | "in_app"—
recipientUserId
querystring (uuid)—
recipientGuardianId
querystring (uuid)—
recipientStudentId
querystring (uuid)—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/notifications" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "channel": "push",
      "status": "queued",
      "toAddress": "string",
      "templateKey": "string",
      "locale": "ar",
      "provider": "string",
      "providerMessageId": "wamid.HBgLMTU1NTU1MTIzNDU=",
      "error": "string",
      "costMinor": -9007199254740991,
      "recipientUserId": "86999436-8699-7699-8999-869994368699",
      "recipientGuardianId": "f98e9636-f98e-798e-88e9-f98e9636f98e",
      "recipientStudentId": "69fd1416-69fd-79fd-8fd1-69fd141669fd",
      "scheduledFor": "2026-03-02T09:00:00.000Z",
      "sentAt": "2026-03-02T09:00:00.000Z",
      "deliveredAt": "2026-03-02T09:00:00.000Z",
      "attempts": -9007199254740991,
      "createdAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/notifications/{id}/retry

Re-queues a failed or skipped notification row.

דורש אימותהרשאהnotifications.send

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/notifications/37386ae0-3738-7738-8386-37386ae03738/retry" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
channelחובה
enum: "push" | "whatsapp" | "email" | "sms" | "in_app"—
statusחובה
enum: "queued" | "sending" | "sent" | "delivered" | "failed" | "skipped"—
toAddressחובה
string—
templateKeyחובה
string—
localeחובה
enum: "ar" | "en" | "he"—
providerחובה
string—
providerMessageIdחובה
string | null≥1 chars
errorחובה
string | null≥1 chars
costMinorחובה
integer | null-9007199254740991–9007199254740991
recipientUserIdחובה
string (uuid) | null—
recipientGuardianIdחובה
string (uuid) | null—
recipientStudentIdחובה
string (uuid) | null—
scheduledForחובה
string (date-time) | null—
sentAtחובה
string (date-time) | null—
deliveredAtחובה
string (date-time) | null—
attemptsחובה
integer-9007199254740991–9007199254740991
createdAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "channel": "push",
  "status": "queued",
  "toAddress": "string",
  "templateKey": "string",
  "locale": "ar",
  "provider": "string",
  "providerMessageId": "wamid.HBgLMTU1NTU1MTIzNDU=",
  "error": "string",
  "costMinor": -9007199254740991,
  "recipientUserId": "86999436-8699-7699-8999-869994368699",
  "recipientGuardianId": "f98e9636-f98e-798e-88e9-f98e9636f98e",
  "recipientStudentId": "69fd1416-69fd-79fd-8fd1-69fd141669fd",
  "scheduledFor": "2026-03-02T09:00:00.000Z",
  "sentAt": "2026-03-02T09:00:00.000Z",
  "deliveredAt": "2026-03-02T09:00:00.000Z",
  "attempts": -9007199254740991,
  "createdAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/notifications/send

Manual broadcast to a group/branch/explicit student list. `dryRun` returns recipient count + quota impact without sending. Naming `channels` explicitly with `sms`/`whatsapp` this tenant is not approved for (`sms_notifications`/`whatsapp_notifications` not effective) is rejected with 422 `VALIDATION_ERROR` rather than silently sending a smaller broadcast; leaving `channels` unset falls through the tenant ladder instead, which skips an unapproved channel silently and still reaches the in-app inbox.

דורש אימותהרשאהnotifications.send

גוף הבקשה

שםסוגמגבלות
templateKey
string1–150 chars
subject
string1–300 chars
body
string1–5000 chars
channels
array<enum: "push" | "whatsapp" | "email" | "sms" | "in_app">—
audienceחובה
object—
payload
objectdefault: {}
urgency
enum: "immediate" | "digest"default: "immediate"
dryRun
booleandefault: false

דוגמה

json
{
  "templateKey": "string",
  "subject": "string",
  "body": "string",
  "channels": [
    "push"
  ],
  "audience": {
    "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
    "branchId": "390b8975-390b-790b-80b8-390b8975390b",
    "studentIds": [
      "af05d28a-af05-7f05-805d-af05d28aaf05"
    ],
    "recipients": "both"
  },
  "payload": {},
  "urgency": "immediate",
  "dryRun": false
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/notifications/send" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "templateKey": "string",
    "subject": "string",
    "body": "string",
    "channels": [
      "push"
    ],
    "audience": {
      "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
      "branchId": "390b8975-390b-790b-80b8-390b8975390b",
      "studentIds": [
        "af05d28a-af05-7f05-805d-af05d28aaf05"
      ],
      "recipients": "both"
    },
    "payload": {},
    "urgency": "immediate",
    "dryRun": false
  }'

תשובות

201
שםסוגמגבלות
dryRunחובה
boolean—
recipientCountחובה
integer-9007199254740991–9007199254740991
queuedחובה
integer-9007199254740991–9007199254740991
skippedחובה
integer-9007199254740991–9007199254740991
notificationIdsחובה
array<string (uuid)>—
channelCountsחובה
object—
quotaImpactחובה
object—
json
{
  "dryRun": true,
  "recipientCount": -9007199254740991,
  "queued": -9007199254740991,
  "skipped": -9007199254740991,
  "notificationIds": [
    "6de4da18-6de4-7de4-8e4d-6de4da186de4"
  ],
  "channelCounts": {},
  "quotaImpact": {}
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/provider-credentials

Lists configured provider credentials — provider id + verified_at only, never secrets.

דורש אימותהרשאהnotifications.manage

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/provider-credentials" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
json
{
  "data": [
    {
      "channel": "push",
      "provider": "string",
      "isActive": true,
      "verifiedAt": "2026-03-02T09:00:00.000Z"
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

DELETE /api/v1/provider-credentials/{channel}

Removes the stored provider credentials for a channel.

דורש אימותהרשאהnotifications.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
channelחובה
pathstring—

דוגמה עם curl

curl
curl -X DELETE "https://your-institute.example/api/v1/provider-credentials/string" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

PUT /api/v1/provider-credentials/{channel}

Sets (envelope-encrypted) provider credentials for a channel. Never echoes the secret back. 403 FEATURE_DISABLED for `sms`/`whatsapp` (platform/licence-approved per tenant, no platform sender exists for either in 1.0.0) or for `email`/`push` when the matching `byo_email_provider`/`byo_push_provider` flag is not granted — the platform SMTP/Expo sender keeps working either way.

דורש אימותהרשאהnotifications.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
channelחובה
pathstring—

גוף הבקשה

שםסוגמגבלות
providerחובה
string1–50 chars
configחובה
object—

דוגמה

json
{
  "provider": "string",
  "config": {}
}

דוגמה עם curl

curl
curl -X PUT "https://your-institute.example/api/v1/provider-credentials/string" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "provider": "string",
    "config": {}
  }'

תשובות

200
שםסוגמגבלות
channelחובה
enum: "push" | "whatsapp" | "email" | "sms" | "in_app"—
providerחובה
string—
isActiveחובה
boolean—
verifiedAtחובה
string (date-time) | null—
json
{
  "channel": "push",
  "provider": "string",
  "isActive": true,
  "verifiedAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/provider-credentials/{channel}/test

Sends a real test message on this channel to the caller's own contact address. Same 403 FEATURE_DISABLED gating as PUT applies here — testing a channel this tenant has not been approved for (or, for email/push, a stored override without byo_email_provider/byo_push_provider) is rejected before anything is sent.

דורש אימותהרשאהnotifications.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
channelחובה
pathstring—

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/provider-credentials/string/test" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

201
שםסוגמגבלות
okחובה
enum: true—
sentToחובה
string—
json
{
  "ok": true,
  "sentTo": "string"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/provider-credentials/status

Per-channel deliverability for this tenant right now — 'own' (approved tenant credentials active), 'platform' (no tenant override, but email/push/in_app always send through Institflow's own sender), or 'unavailable' (sms/whatsapp with no approved, configured tenant credential — the only case nothing sends). No permission required and carries no secret: every screen that plans a send (the broadcast wizard, the invoices reminder banner, the onboarding checklist) reads this instead of guessing from the credentials list.

דורש אימותהרשאהללא הרשאה נוספת

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/provider-credentials/status" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
json
{
  "data": [
    {
      "channel": "push",
      "status": "own",
      "reason": "Requested by guardian."
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

DELETE /api/v1/push-devices

Unregisters the caller's own push device token.

דורש אימותהרשאהללא הרשאה נוספת

גוף הבקשה

שםסוגמגבלות
tokenחובה
string1–4096 chars

דוגמה

json
{
  "token": "string"
}

דוגמה עם curl

curl
curl -X DELETE "https://your-institute.example/api/v1/push-devices" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "token": "string"
  }'

תשובות

200
שםסוגמגבלות
okחובה
enum: true—
json
{
  "ok": true
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/push-devices

Registers (or refreshes) the caller's own push device token.

דורש אימותהרשאהללא הרשאה נוספת

גוף הבקשה

שםסוגמגבלות
platformחובה
enum: "ios" | "android" | "web"—
tokenחובה
string1–4096 chars

דוגמה

json
{
  "platform": "ios",
  "token": "string"
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/push-devices" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "platform": "ios",
    "token": "string"
  }'

תשובות

201
שםסוגמגבלות
okחובה
enum: true—
json
{
  "ok": true
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/web-push/config

Whether this server can send browser push and, if so, the public key to subscribe with. `enabled: false` means the page should offer no browser-notification controls.

דורש אימותהרשאהללא הרשאה נוספת

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/web-push/config" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
enabledחובה
boolean—
publicKeyחובה
string | null—
json
{
  "enabled": true,
  "publicKey": "string"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

DELETE /api/v1/web-push/subscriptions

Removes the caller's own browser push subscription for an endpoint (idempotent).

דורש אימותהרשאהללא הרשאה נוספת

גוף הבקשה

שםסוגמגבלות
endpointחובה
string0–2048 chars

דוגמה

json
{
  "endpoint": "string"
}

דוגמה עם curl

curl
curl -X DELETE "https://your-institute.example/api/v1/web-push/subscriptions" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "endpoint": "string"
  }'

תשובות

200
שםסוגמגבלות
okחובה
enum: true—
json
{
  "ok": true
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/web-push/subscriptions

Registers (or refreshes) the caller's browser push subscription (`PushSubscription.toJSON()`). Refused with a feature-disabled error while the server has no push transport.

דורש אימותהרשאהללא הרשאה נוספת

גוף הבקשה

שםסוגמגבלות
endpointחובה
string0–2048 chars
keysחובה
object—
userAgent
string0–200 chars

דוגמה

json
{
  "endpoint": "string",
  "keys": {
    "p256dh": "string",
    "auth": "string"
  },
  "userAgent": "string"
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/web-push/subscriptions" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "endpoint": "string",
    "keys": {
      "p256dh": "string",
      "auth": "string"
    },
    "userAgent": "string"
  }'

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/webhooks/providers/{provider}

Inbound delivery-status webhook from a notification provider (Meta/Twilio). Signature-verified.

ללא אימותהרשאהציבורית

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
providerחובה
pathstring—

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/webhooks/providers/string" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

401Missing, expired or invalid credentials (`UNAUTHORIZED`, `TOKEN_INVALID`, `SESSION_REVOKED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

403Authenticated, but not allowed (`FORBIDDEN`, `FEATURE_DISABLED`, `QUOTA_EXCEEDED`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

404No such resource, or it is not visible to this tenant (`NOT_FOUND`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

409Conflicts with current state (`CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

429Rate limit exceeded — see the `RateLimit-*` and `Retry-After` headers (`RATE_LIMITED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

500Unexpected server error (`INTERNAL_ERROR`). Never carries a stack trace or SQL.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.