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 endpoints

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.

No authenticationScopePublic

Request body

Name	Type	Constraints
setupTokenrequired	string	≥1 chars
instituterequired	object	—
ownerrequired	object	—

Example

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 example

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"
    }
  }'

Responses

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.

Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.

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

Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.

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

Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.

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

Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.

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

Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.

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`, …).

Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.

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

Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.

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

Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.

GET `/api/v1/setup/status`

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

No authenticationScopePublic

curl example

curl

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

Responses

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

Name	Type	Constraints
deploymentModerequired	enum: "cloud" \| "self_hosted"	—
needsSetuprequired	boolean	—

json

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