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? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.