tenancy

Settings & Branches

Branches, tenant settings, feature flags, license status, and subscription status.

18 נקודות קצה

GET /api/v1/branches

List every branch in the active tenant (any member may read).

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

דוגמה עם curl

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

תשובות

200The tenant’s branches.
json
[
  {
    "id": "37386ae0-3738-7738-8386-37386ae03738",
    "tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
    "name": "Algebra I",
    "code": "string",
    "address": {},
    "phone": "+15551234567",
    "isDefault": true,
    "isActive": 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? } }`. כל הקודים מפורטים במדריך המוסכמות.

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/branches

Create a branch. Names must be unique per tenant.

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

גוף הבקשה

שםסוגמגבלות
nameחובה
string1–200 chars
code
enum: "" | string—
address
object—
phone
enum: "" | string—
isDefault
boolean—

דוגמה

json
{
  "name": "Algebra I",
  "code": "",
  "address": {},
  "phone": "",
  "isDefault": true
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/branches" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Algebra I",
    "code": "",
    "address": {},
    "phone": "",
    "isDefault": true
  }'

תשובות

201The newly created branch.
שםסוגמגבלות
idחובה
string (uuid)—
tenantIdחובה
string (uuid)—
nameחובה
string—
codeחובה
string | null≥1 chars
addressחובה
object | null—
phoneחובה
string | null≥1 chars
isDefaultחובה
boolean—
isActiveחובה
boolean—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
  "name": "Algebra I",
  "code": "string",
  "address": {},
  "phone": "+15551234567",
  "isDefault": true,
  "isActive": 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/branches/{id}

Delete a branch. The default branch, and any branch with role assignments, cannot be deleted (409).

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

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

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

דוגמה עם curl

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

תשובות

200The branch was deleted.
שםסוגמגבלות
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? } }`. כל הקודים מפורטים במדריך המוסכמות.

PATCH /api/v1/branches/{id}

Update a branch. Setting `isDefault: true` clears the previous default branch.

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

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

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

גוף הבקשה

שםסוגמגבלות
name
string1–200 chars
code
enum: "" | string | null—
address
object | null—
phone
enum: "" | string | null—
isDefault
boolean—
isActive
boolean—

דוגמה

json
{
  "name": "Algebra I",
  "code": "",
  "address": {},
  "phone": "",
  "isDefault": true,
  "isActive": true
}

דוגמה עם curl

curl
curl -X PATCH "https://your-institute.example/api/v1/branches/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Algebra I",
    "code": "",
    "address": {},
    "phone": "",
    "isDefault": true,
    "isActive": true
  }'

תשובות

200The updated branch.
שםסוגמגבלות
idחובה
string (uuid)—
tenantIdחובה
string (uuid)—
nameחובה
string—
codeחובה
string | null≥1 chars
addressחובה
object | null—
phoneחובה
string | null≥1 chars
isDefaultחובה
boolean—
isActiveחובה
boolean—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
  "name": "Algebra I",
  "code": "string",
  "address": {},
  "phone": "+15551234567",
  "isDefault": true,
  "isActive": 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? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/feature-flags

Effective feature flags for the active tenant (registry defaults merged with the plan and tenant overrides).

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

דוגמה עם curl

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

תשובות

200The tenant’s effective feature flags.
שםסוגמגבלות
basic_reportsחובה
boolean—
advanced_reportsחובה
boolean—
integration_apiחובה
boolean—
mcpחובה
boolean—
custom_domainחובה
boolean—
whatsapp_notificationsחובה
boolean—
sms_notificationsחובה
boolean—
byo_email_providerחובה
boolean—
byo_push_providerחובה
boolean—
courses_videoחובה
boolean—
json
{
  "basic_reports": true,
  "advanced_reports": true,
  "integration_api": true,
  "mcp": true,
  "custom_domain": true,
  "whatsapp_notifications": true,
  "sms_notifications": true,
  "byo_email_provider": true,
  "byo_push_provider": true,
  "courses_video": 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? } }`. כל הקודים מפורטים במדריך המוסכמות.

PATCH /api/v1/feature-flags

Toggle feature flags. Platform-managed in cloud deployments (403 here); in self_hosted deployments the tenant owner may toggle self-manageable flags only.

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

גוף הבקשה

אין.

דוגמה

json
{}

דוגמה עם curl

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

תשובות

200The tenant’s new effective feature flags.
שםסוגמגבלות
basic_reportsחובה
boolean—
advanced_reportsחובה
boolean—
integration_apiחובה
boolean—
mcpחובה
boolean—
custom_domainחובה
boolean—
whatsapp_notificationsחובה
boolean—
sms_notificationsחובה
boolean—
byo_email_providerחובה
boolean—
byo_push_providerחובה
boolean—
courses_videoחובה
boolean—
json
{
  "basic_reports": true,
  "advanced_reports": true,
  "integration_api": true,
  "mcp": true,
  "custom_domain": true,
  "whatsapp_notifications": true,
  "sms_notifications": true,
  "byo_email_provider": true,
  "byo_push_provider": true,
  "courses_video": 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/license

This self-hosted instance’s license state (self_hosted deployments only).

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

דוגמה עם curl

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

תשובות

200The instance’s license summary.
שםסוגמגבלות
planחובה
string—
limitsחובה
object—
featuresחובה
array<string>—
expiresAtחובה
string (date-time)—
stateחובה
enum: "valid" | "expired" | "locked" | "revoked"—
lockedByCommandחובה
boolean—
lastServerContactAtחובה
string (date-time) | null—
lastServerTimeחובה
string (date-time) | null—
consecutiveFailuresחובה
integer0–9007199254740991
installIdחובה
string—
tamperSignalsחובה
array<object>—
json
{
  "plan": "string",
  "limits": {},
  "features": [
    "string"
  ],
  "expiresAt": "2026-03-02T09:00:00.000Z",
  "state": "valid",
  "lockedByCommand": true,
  "lastServerContactAt": "2026-03-02T09:00:00.000Z",
  "lastServerTime": "2026-03-02T09:00:00.000Z",
  "consecutiveFailures": 0,
  "installId": "2472867d-2472-7472-8728-2472867d2472",
  "tamperSignals": [
    {
      "kind": "state_signature_invalid",
      "detectedAt": "2026-03-02T09:00:00.000Z",
      "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

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/license/apply-token

Apply a signed offline unlock token issued by the license server (self_hosted only).

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

גוף הבקשה

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

דוגמה

json
{
  "token": "string"
}

דוגמה עם curl

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

תשובות

200The instance’s license summary after the token was applied.
שםסוגמגבלות
planחובה
string—
limitsחובה
object—
featuresחובה
array<string>—
expiresAtחובה
string (date-time)—
stateחובה
enum: "valid" | "expired" | "locked" | "revoked"—
lockedByCommandחובה
boolean—
lastServerContactAtחובה
string (date-time) | null—
lastServerTimeחובה
string (date-time) | null—
consecutiveFailuresחובה
integer0–9007199254740991
installIdחובה
string—
tamperSignalsחובה
array<object>—
json
{
  "plan": "string",
  "limits": {},
  "features": [
    "string"
  ],
  "expiresAt": "2026-03-02T09:00:00.000Z",
  "state": "valid",
  "lockedByCommand": true,
  "lastServerContactAt": "2026-03-02T09:00:00.000Z",
  "lastServerTime": "2026-03-02T09:00:00.000Z",
  "consecutiveFailures": 0,
  "installId": "2472867d-2472-7472-8728-2472867d2472",
  "tamperSignals": [
    {
      "kind": "state_signature_invalid",
      "detectedAt": "2026-03-02T09:00:00.000Z",
      "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/license/updates

This install’s update channel status (self_hosted deployments only).

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

דוגמה עם curl

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

תשובות

200The install’s update status.
שםסוגמגבלות
autoUpdateחובה
boolean—
channelחובה
enum: "stable" | "beta"—
currentVersionחובה
string—
checkRequestedAtחובה
string (date-time) | null—
updatesBlockedחובה
boolean—
blockedReasonחובה
string | null—
lastCheckAtחובה
string (date-time) | null—
lastResultחובה
enum: "up_to_date" | "updated" | "rolled_back" | "failed" | "skipped" | null | null—
reasonחובה
enum: "none" | "auto_update_off" | "min_from_version" | "locked" | "migration_running" | "manifest_unreachable" | "bad_signature" | "channel_mismatch" | "digest_mismatch" | "docker_error" | "health_check_failed" | "api_unreachable" | "setup_pending" | null | null—
targetVersionחובה
string | null—
detailחובה
string | null—
updaterPresentחובה
boolean—
storageUpgradeNeededחובה
boolean—
json
{
  "autoUpdate": true,
  "channel": "stable",
  "currentVersion": "string",
  "checkRequestedAt": "2026-03-02T09:00:00.000Z",
  "updatesBlocked": true,
  "blockedReason": "string",
  "lastCheckAt": "2026-03-02T09:00:00.000Z",
  "lastResult": "up_to_date",
  "reason": "none",
  "targetVersion": "string",
  "detail": "string",
  "updaterPresent": true,
  "storageUpgradeNeeded": 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? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/license/updates/check

Ask the updater to check for a new release now instead of waiting for its next interval.

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

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/license/updates/check" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200The install’s update status, with the check request recorded.
שםסוגמגבלות
autoUpdateחובה
boolean—
channelחובה
enum: "stable" | "beta"—
currentVersionחובה
string—
checkRequestedAtחובה
string (date-time) | null—
updatesBlockedחובה
boolean—
blockedReasonחובה
string | null—
lastCheckAtחובה
string (date-time) | null—
lastResultחובה
enum: "up_to_date" | "updated" | "rolled_back" | "failed" | "skipped" | null | null—
reasonחובה
enum: "none" | "auto_update_off" | "min_from_version" | "locked" | "migration_running" | "manifest_unreachable" | "bad_signature" | "channel_mismatch" | "digest_mismatch" | "docker_error" | "health_check_failed" | "api_unreachable" | "setup_pending" | null | null—
targetVersionחובה
string | null—
detailחובה
string | null—
updaterPresentחובה
boolean—
storageUpgradeNeededחובה
boolean—
json
{
  "autoUpdate": true,
  "channel": "stable",
  "currentVersion": "string",
  "checkRequestedAt": "2026-03-02T09:00:00.000Z",
  "updatesBlocked": true,
  "blockedReason": "string",
  "lastCheckAt": "2026-03-02T09:00:00.000Z",
  "lastResult": "up_to_date",
  "reason": "none",
  "targetVersion": "string",
  "detail": "string",
  "updaterPresent": true,
  "storageUpgradeNeeded": 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/onboarding

First-run checklist for the active tenant: per-step done/count for the institute profile, branches, courses, groups, students, fees, notification channels and team. Cached 60s.

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

דוגמה עם curl

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

תשובות

200The tenant’s onboarding progress.
שםסוגמגבלות
stepsחובה
array<object>—
completedStepsחובה
integer0–9007199254740991
totalStepsחובה
integer0–9007199254740991
isCompleteחובה
boolean—
countsחובה
object—
json
{
  "steps": [
    {
      "key": "institute",
      "done": true,
      "count": 0
    }
  ],
  "completedSteps": 0,
  "totalSteps": 0,
  "isComplete": true,
  "counts": {
    "branches": 0,
    "courses": 0,
    "groups": 0,
    "students": 0,
    "feeSchedules": 0,
    "invoices": 0,
    "staff": 0,
    "members": 0,
    "notificationChannels": 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? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/relay/sender-name

Submit this institute’s requested display name for institute-mode email, for the vendor to approve. self_hosted only.

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

גוף הבקשה

שםסוגמגבלות
displayNameחובה
string1–70 chars

דוגמה

json
{
  "displayName": "string"
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/relay/sender-name" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "displayName": "string"
  }'

תשובות

200The relay status after the request was recorded.
שםסוגמגבלות
enrolmentStatusחובה
enum: "unenrolled" | "pending" | "approved" | "blocked"—
requestedSenderDisplayNameחובה
string | null≥1 chars
lastErrorMessageחובה
string | null≥1 chars
lastErrorAtחובה
string (date-time) | null—
accountחובה
object | null—
json
{
  "enrolmentStatus": "unenrolled",
  "requestedSenderDisplayName": "string",
  "lastErrorMessage": "string",
  "lastErrorAt": "2026-03-02T09:00:00.000Z",
  "account": {
    "balanceUnits": -9007199254740991,
    "overdraftUnits": -9007199254740991,
    "status": "active",
    "reputationHold": true,
    "relayEmailEnabled": true,
    "installStatus": "approved",
    "prices": [
      {
        "senderMode": "platform",
        "priceUnits": -9007199254740991
      }
    ],
    "senderName": {
      "displayName": "string",
      "state": "none"
    },
    "asOf": "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/relay/status

This install’s relay enrolment and last known account snapshot (balance, overdraft, prices, sender-name state). self_hosted only.

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

דוגמה עם curl

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

תשובות

200The relay status.
שםסוגמגבלות
enrolmentStatusחובה
enum: "unenrolled" | "pending" | "approved" | "blocked"—
requestedSenderDisplayNameחובה
string | null≥1 chars
lastErrorMessageחובה
string | null≥1 chars
lastErrorAtחובה
string (date-time) | null—
accountחובה
object | null—
json
{
  "enrolmentStatus": "unenrolled",
  "requestedSenderDisplayName": "string",
  "lastErrorMessage": "string",
  "lastErrorAt": "2026-03-02T09:00:00.000Z",
  "account": {
    "balanceUnits": -9007199254740991,
    "overdraftUnits": -9007199254740991,
    "status": "active",
    "reputationHold": true,
    "relayEmailEnabled": true,
    "installStatus": "approved",
    "prices": [
      {
        "senderMode": "platform",
        "priceUnits": -9007199254740991
      }
    ],
    "senderName": {
      "displayName": "string",
      "state": "none"
    },
    "asOf": "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/settings

Effective settings for the active tenant (registry defaults merged with stored overrides). With `settings.manage` the whole registry; for any other member or key only the member view (institute name, default locale, timezone, currency, SMS enabled). The 18 per-type notification keys are deprecated aliases derived from the notification rules (GET /notification-rules).

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

דוגמה עם curl

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

תשובות

200The tenant’s effective settings — the full registry, or the member view without `settings.manage`.
שםסוגמגבלות
general.name
string1–200 chars
general.timezone
string1–100 chars
general.currency
string3–3 chars
general.defaultLocale
enum: "ar" | "en" | "he"—
general.logoFileId
string (uuid) | null—
general.contactEmail
string (email) | null0–320 chars
general.contactPhone
string | null1–50 chars
general.address
string | null1–500 chars
attendance.lateThresholdMinutes
integer0–120
attendance.notifyGuardianOnAbsence
boolean—
attendance.warnBelowRate
integer0–100
attendance.criticalBelowRate
integer0–100
grading.scale
enum: "percentage" | "letter" | "custom"—
assessment.autoSendOnPublish
boolean—
billing.invoiceDueDays
integer0–365
billing.allowOverpayment
boolean—
billing.invoicePrefix
string1–10 chars
billing.autoInvoiceOnEnrollment
boolean—
notifications.smsEnabled
boolean—
notifications.digestHourLocal
integer0–23
notifications.quietHours
object | null—
notifications.email.senderMode
enum: "platform" | "institute"—
notifications.email.displayName
string | null1–70 chars
notifications.email.replyTo
string (email) | null0–320 chars
notifications.paidEmail.invoiceIssued
boolean—
notifications.paidEmail.invoiceOverdue
boolean—
notifications.paidEmail.paymentReceipt
boolean—
notifications.paidEmail.enrollmentWelcome
boolean—
notifications.paidEmail.examPublished
boolean—
notifications.paidEmail.courseCompleted
boolean—
notifications.paidEmail.assignmentPublished
boolean—
notifications.paidEmail.assignmentSubmitted
boolean—
notifications.paidEmail.assignmentGraded
boolean—
notifications.paidEmail.quizPublished
boolean—
notifications.paidEmail.quizSubmitted
boolean—
notifications.paidEmail.quizGraded
boolean—
notifications.paidEmail.digestEnabled
boolean—
notifications.channelLadder
array<enum: "push" | "whatsapp" | "email" | "sms" | "in_app">—
curriculum.autoCompleteThresholdPercent
integer50–100
curriculum.notifyOnLessonPublished
boolean—
reminders.classStartsSoon
boolean—
reminders.workDueTomorrow
boolean—
reminders.emailEnabled
boolean—
updates.autoUpdate
boolean—
updates.channel
enum: "stable" | "beta"—
updates.repairMode
enum: "repair" | "report"—
integration.publicCatalogueEnabled
boolean—
integration.captchaSiteKey
string | null1–200 chars
integration.registrationsToLeads
boolean—
loginDiscovery.staffEmails
array<string (email)>—
json
{
  "general.name": "string",
  "general.timezone": "string",
  "general.currency": "USD",
  "general.defaultLocale": "ar",
  "general.logoFileId": "5987666b-5987-7987-8876-5987666b5987",
  "general.contactEmail": "ada.lovelace@example.com",
  "general.contactPhone": "string",
  "general.address": "string",
  "attendance.lateThresholdMinutes": 0,
  "attendance.notifyGuardianOnAbsence": true,
  "attendance.warnBelowRate": 0,
  "attendance.criticalBelowRate": 0,
  "grading.scale": "percentage",
  "assessment.autoSendOnPublish": true,
  "billing.invoiceDueDays": 0,
  "billing.allowOverpayment": true,
  "billing.invoicePrefix": "string",
  "billing.autoInvoiceOnEnrollment": true,
  "notifications.smsEnabled": true,
  "notifications.digestHourLocal": 0,
  "notifications.quietHours": {
    "start": "string",
    "end": "string"
  },
  "notifications.email.senderMode": "platform",
  "notifications.email.displayName": "string",
  "notifications.email.replyTo": "ada.lovelace@example.com",
  "notifications.paidEmail.invoiceIssued": true,
  "notifications.paidEmail.invoiceOverdue": true,
  "notifications.paidEmail.paymentReceipt": true,
  "notifications.paidEmail.enrollmentWelcome": true,
  "notifications.paidEmail.examPublished": true,
  "notifications.paidEmail.courseCompleted": true,
  "notifications.paidEmail.assignmentPublished": true,
  "notifications.paidEmail.assignmentSubmitted": true,
  "notifications.paidEmail.assignmentGraded": true,
  "notifications.paidEmail.quizPublished": true,
  "notifications.paidEmail.quizSubmitted": true,
  "notifications.paidEmail.quizGraded": true,
  "notifications.paidEmail.digestEnabled": true,
  "notifications.channelLadder": [
    "push"
  ],
  "curriculum.autoCompleteThresholdPercent": 50,
  "curriculum.notifyOnLessonPublished": true,
  "reminders.classStartsSoon": true,
  "reminders.workDueTomorrow": true,
  "reminders.emailEnabled": true,
  "updates.autoUpdate": true,
  "updates.channel": "stable",
  "updates.repairMode": "repair",
  "integration.publicCatalogueEnabled": true,
  "integration.captchaSiteKey": "string",
  "integration.registrationsToLeads": true,
  "loginDiscovery.staffEmails": [
    "ada.lovelace@example.com"
  ]
}
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? } }`. כל הקודים מפורטים במדריך המוסכמות.

PATCH /api/v1/settings

Update one or more settings. An unknown key, or an invalid value, is rejected (422). A write to a deprecated per-type notification key is translated into the matching notification rule and answered with a `Deprecation` header; a write that would raise what the institute pays for (a paid channel or a type switched on, a wider audience) is refused with 422 `legacy_write_raises_paid_exposure` — use `PUT /notification-rules/{typeKey}` with `confirmCost` instead.

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

גוף הבקשה

אין.

דוגמה

json
{}

דוגמה עם curl

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

תשובות

200The tenant’s new effective settings.
שםסוגמגבלות
general.nameחובה
string1–200 chars
general.timezoneחובה
string1–100 chars
general.currencyחובה
string3–3 chars
general.defaultLocaleחובה
enum: "ar" | "en" | "he"—
general.logoFileIdחובה
string (uuid) | null—
general.contactEmailחובה
string (email) | null0–320 chars
general.contactPhoneחובה
string | null1–50 chars
general.addressחובה
string | null1–500 chars
attendance.lateThresholdMinutesחובה
integer0–120
attendance.notifyGuardianOnAbsenceחובה
boolean—
attendance.warnBelowRateחובה
integer0–100
attendance.criticalBelowRateחובה
integer0–100
grading.scaleחובה
enum: "percentage" | "letter" | "custom"—
assessment.autoSendOnPublishחובה
boolean—
billing.invoiceDueDaysחובה
integer0–365
billing.allowOverpaymentחובה
boolean—
billing.invoicePrefixחובה
string1–10 chars
billing.autoInvoiceOnEnrollmentחובה
boolean—
notifications.smsEnabledחובה
boolean—
notifications.digestHourLocalחובה
integer0–23
notifications.quietHoursחובה
object | null—
notifications.email.senderModeחובה
enum: "platform" | "institute"—
notifications.email.displayNameחובה
string | null1–70 chars
notifications.email.replyToחובה
string (email) | null0–320 chars
notifications.paidEmail.invoiceIssuedחובה
boolean—
notifications.paidEmail.invoiceOverdueחובה
boolean—
notifications.paidEmail.paymentReceiptחובה
boolean—
notifications.paidEmail.enrollmentWelcomeחובה
boolean—
notifications.paidEmail.examPublishedחובה
boolean—
notifications.paidEmail.courseCompletedחובה
boolean—
notifications.paidEmail.assignmentPublishedחובה
boolean—
notifications.paidEmail.assignmentSubmittedחובה
boolean—
notifications.paidEmail.assignmentGradedחובה
boolean—
notifications.paidEmail.quizPublishedחובה
boolean—
notifications.paidEmail.quizSubmittedחובה
boolean—
notifications.paidEmail.quizGradedחובה
boolean—
notifications.paidEmail.digestEnabledחובה
boolean—
notifications.channelLadderחובה
array<enum: "push" | "whatsapp" | "email" | "sms" | "in_app">—
curriculum.autoCompleteThresholdPercentחובה
integer50–100
curriculum.notifyOnLessonPublishedחובה
boolean—
reminders.classStartsSoonחובה
boolean—
reminders.workDueTomorrowחובה
boolean—
reminders.emailEnabledחובה
boolean—
updates.autoUpdateחובה
boolean—
updates.channelחובה
enum: "stable" | "beta"—
updates.repairModeחובה
enum: "repair" | "report"—
integration.publicCatalogueEnabledחובה
boolean—
integration.captchaSiteKeyחובה
string | null1–200 chars
integration.registrationsToLeadsחובה
boolean—
loginDiscovery.staffEmailsחובה
array<string (email)>—
json
{
  "general.name": "string",
  "general.timezone": "string",
  "general.currency": "USD",
  "general.defaultLocale": "ar",
  "general.logoFileId": "5987666b-5987-7987-8876-5987666b5987",
  "general.contactEmail": "ada.lovelace@example.com",
  "general.contactPhone": "string",
  "general.address": "string",
  "attendance.lateThresholdMinutes": 0,
  "attendance.notifyGuardianOnAbsence": true,
  "attendance.warnBelowRate": 0,
  "attendance.criticalBelowRate": 0,
  "grading.scale": "percentage",
  "assessment.autoSendOnPublish": true,
  "billing.invoiceDueDays": 0,
  "billing.allowOverpayment": true,
  "billing.invoicePrefix": "string",
  "billing.autoInvoiceOnEnrollment": true,
  "notifications.smsEnabled": true,
  "notifications.digestHourLocal": 0,
  "notifications.quietHours": {
    "start": "string",
    "end": "string"
  },
  "notifications.email.senderMode": "platform",
  "notifications.email.displayName": "string",
  "notifications.email.replyTo": "ada.lovelace@example.com",
  "notifications.paidEmail.invoiceIssued": true,
  "notifications.paidEmail.invoiceOverdue": true,
  "notifications.paidEmail.paymentReceipt": true,
  "notifications.paidEmail.enrollmentWelcome": true,
  "notifications.paidEmail.examPublished": true,
  "notifications.paidEmail.courseCompleted": true,
  "notifications.paidEmail.assignmentPublished": true,
  "notifications.paidEmail.assignmentSubmitted": true,
  "notifications.paidEmail.assignmentGraded": true,
  "notifications.paidEmail.quizPublished": true,
  "notifications.paidEmail.quizSubmitted": true,
  "notifications.paidEmail.quizGraded": true,
  "notifications.paidEmail.digestEnabled": true,
  "notifications.channelLadder": [
    "push"
  ],
  "curriculum.autoCompleteThresholdPercent": 50,
  "curriculum.notifyOnLessonPublished": true,
  "reminders.classStartsSoon": true,
  "reminders.workDueTomorrow": true,
  "reminders.emailEnabled": true,
  "updates.autoUpdate": true,
  "updates.channel": "stable",
  "updates.repairMode": "repair",
  "integration.publicCatalogueEnabled": true,
  "integration.captchaSiteKey": "string",
  "integration.registrationsToLeads": true,
  "loginDiscovery.staffEmails": [
    "ada.lovelace@example.com"
  ]
}
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/subscription

This tenant’s subscription: plan, status, current period, lock timestamp, and plan limits. Always readable, even while locked.

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

דוגמה עם curl

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

תשובות

200The tenant’s subscription.
שםסוגמגבלות
planחובה
object—
statusחובה
enum: "trialing" | "active" | "expired" | "suspended" | "cancelled"—
currentPeriodStartחובה
string (date-time)—
currentPeriodEndחובה
string (date-time)—
lockedAtחובה
string (date-time) | null—
limitsחובה
PlanLimits—
json
{
  "plan": {
    "id": "37386ae0-3738-7738-8386-37386ae03738",
    "code": "string",
    "name": "Algebra I"
  },
  "status": "trialing",
  "currentPeriodStart": "2026-03-02T09:00:00.000Z",
  "currentPeriodEnd": "2026-03-02T09:00:00.000Z",
  "lockedAt": "2026-03-02T09:00:00.000Z",
  "limits": {
    "maxStudents": -9007199254740991,
    "maxBranches": -9007199254740991,
    "maxVideoCourses": -9007199254740991,
    "maxLessonsPerCourse": -9007199254740991,
    "notificationQuota": {
      "whatsapp": -9007199254740991,
      "sms": -9007199254740991,
      "email": "ada.lovelace@example.com"
    }
  }
}
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/tenants/{tenantId}/branding

The institute's public branding for the installable app: display name, default language and whether it has a logo. Anonymous; an unknown or inactive institute is a 404.

ללא אימותהרשאהציבורית

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

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

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/tenants/4332af8b-4332-7332-832a-4332af8b4332/branding" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
nameחובה
string—
defaultLocaleחובה
enum: "ar" | "en" | "he"—
hasLogoחובה
boolean—
json
{
  "name": "Algebra I",
  "defaultLocale": "ar",
  "hasLogo": 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? } }`. כל הקודים מפורטים במדריך המוסכמות.

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? } }`. כל הקודים מפורטים במדריך המוסכמות.

The institute's logo bytes (PNG, JPEG or WebP, at most 5 MB). Anonymous; 404 when the institute is unknown or inactive or has no logo.

ללא אימותהרשאהציבורית

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

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

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/tenants/4332af8b-4332-7332-832a-4332af8b4332/branding/logo" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200The logo image.

מסמך ה-OpenAPI של הממשק עדיין לא מגדיר סכמה מטופסת לתשובה הזו — התשובה עדיין JSON תקין, היא פשוט לא מתועדת כאן.

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? } }`. כל הקודים מפורטים במדריך המוסכמות.