install

One-Step Install

The customer-facing half of the one-step install: claim a one-time install token (issues a licence, a registry credential and an address under institflow.app, and hands back the current bundle) and download the installer script. Unauthenticated — the caller is an installer script on a customer's own server, not a platform-admin session.

2 endpoints

POST `/api/v1/install/claim`

Claim a one-time install token: issues a licence, a registry credential, an address under institflow.app, and the current bundle. Every failure reason (wrong/used/expired/revoked token, ended customer, invalid licence) answers the same 404.

No authenticationScopePublic

Request body

Name	Type	Constraints
tokenrequired	string	1–4096 chars
installIdrequired	string (uuid)	—
publicKey	string	1–4000 chars
serverIp	string	1–64 chars
hostname	string	1–255 chars
version	string	1–64 chars
domain	string	1–253 chars

Example

json

{
  "token": "string",
  "installId": "2472867d-2472-7472-8728-2472867d2472",
  "publicKey": "string",
  "serverIp": "string",
  "hostname": "string",
  "version": "string",
  "domain": "string"
}

curl example

curl

curl -X POST "https://your-institute.example/api/v1/install/claim" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "token": "string",
    "installId": "2472867d-2472-7472-8728-2472867d2472",
    "publicKey": "string",
    "serverIp": "string",
    "hostname": "string",
    "version": "string",
    "domain": "string"
  }'

Responses

201Everything the installer needs, once.

Name	Type	Constraints
licenseKeyrequired	string	—
registryrequired	object	—
addressrequired	string	—
bundlerequired	object	—
tenantrequired	object	—

json

{
  "licenseKey": "string",
  "registry": {
    "host": "string",
    "username": "string",
    "password": "string"
  },
  "address": "string",
  "bundle": {
    "version": "string",
    "files": {
      "compose": "string",
      "envExample": "string",
      "caddyfile": "string"
    }
  },
  "tenant": {
    "slug": "string",
    "name": "Algebra I",
    "defaultLocale": "ar"
  }
}

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/install/script`

The one-step installer script (docker/install.sh), baked into the image. X-Institflow-Script-Sha256 lets a careful customer compare before running it.

No authenticationScopePublic

curl example

curl

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

Responses

200The installer script, as a Bash file.

The API's OpenAPI spec doesn't declare a typed schema for this response yet — it's still JSON, just not documented here.