setup

First-run Setup

Unauthenticated first-run bootstrap of a self-hosted install: whether this deployment still needs setup, and the one call that creates its institute and owner account. Both answer 404 on the cloud platform and once an institute exists.

2 نقاط النهاية

POST `/api/v1/setup/bootstrap`

Create this self-hosted install's institute and its owner account, and sign the owner in. 404 in cloud mode or once an institute exists.

بدون مصادقةالصلاحيةعامة

محتوى الطلب

الاسم	النوع	القيود
setupTokenمطلوب	string	≥1 chars
instituteمطلوب	object	—
ownerمطلوب	object	—

مثال

json

{
  "setupToken": "string",
  "institute": {
    "slug": "string",
    "name": "Algebra I",
    "defaultLocale": "ar",
    "timezone": "string",
    "currency": "USD"
  },
  "owner": {
    "email": "ada.lovelace@example.com",
    "password": "string",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }
}

مثال بأمر curl

curl

curl -X POST "https://your-institute.example/api/v1/setup/bootstrap" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "setupToken": "string",
    "institute": {
      "slug": "string",
      "name": "Algebra I",
      "defaultLocale": "ar",
      "timezone": "string",
      "currency": "USD"
    },
    "owner": {
      "email": "ada.lovelace@example.com",
      "password": "string",
      "firstName": "Ada",
      "lastName": "Lovelace"
    }
  }'

الاستجابات

201An access token for the new owner, their membership, and the institute's id.

json

{
  "mfaRequired": true,
  "mfaEnrollmentRequired": true,
  "mfaToken": "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? } }`. جميع الرموز مذكورة في دليل الاصطلاحات.

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/setup/status`

Whether this deployment still needs first-run setup. Public: the login page reads it before any session exists.

بدون مصادقةالصلاحيةعامة

مثال بأمر curl

curl

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

الاستجابات

200The deployment mode and whether an institute has been created yet.

الاسم	النوع	القيود
deploymentModeمطلوب	enum: "cloud" \| "self_hosted"	—
needsSetupمطلوب	boolean	—

json

{
  "deploymentMode": "cloud",
  "needsSetup": true
}