platform
Platform Admin
Cross-tenant platform administration: tenants, plans, licenses, custom domains, subscriptions, platform users, and job queues. Requires a platform-admin account, not a tenant membership.
116 endpoints
DELETE /api/v1/platform/accounts/links
Remove a student/guardian institute link. Idempotent — already-removed is returned as-is.
Request body
| Name | Type | Constraints |
|---|---|---|
kindrequired | enum: "student" | "guardian" | — |
emailrequired | string (email) | 0–320 chars |
Example
{
"kind": "student",
"email": "ada.lovelace@example.com"
}curl example
curl -X DELETE "https://your-institute.example/api/v1/platform/accounts/links" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"kind": "student",
"email": "ada.lovelace@example.com"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
kindrequired | enum: "student" | "guardian" | — |
statusrequired | enum: "invited" | "active" | "removed" | "declined" | — |
invitedAtrequired | string (date-time) | null | — |
activatedAtrequired | string (date-time) | null | — |
removedAtrequired | string (date-time) | null | — |
declinedAtrequired | string (date-time) | null | — |
inviteEmailSentAtrequired | string (date-time) | null | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"kind": "student",
"status": "invited",
"invitedAt": "2026-03-02T09:00:00.000Z",
"activatedAt": "2026-03-02T09:00:00.000Z",
"removedAt": "2026-03-02T09:00:00.000Z",
"declinedAt": "2026-03-02T09:00:00.000Z",
"inviteEmailSentAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/accounts/links
This install's own institute links, newest first — never another install's or the account's other institutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/accounts/links" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"kind": "student",
"status": "invited",
"invitedAt": "2026-03-02T09:00:00.000Z",
"activatedAt": "2026-03-02T09:00:00.000Z",
"removedAt": "2026-03-02T09:00:00.000Z",
"declinedAt": "2026-03-02T09:00:00.000Z",
"inviteEmailSentAt": "2026-03-02T09:00:00.000Z"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/accounts/links
Invite a student/guardian by email to this institute. Idempotent on the link — a repeat returns the existing link; the invitation email is sent again only if it was never delivered, or when `resend` is set and the last send is at least two minutes old.
Request body
| Name | Type | Constraints |
|---|---|---|
kindrequired | enum: "student" | "guardian" | — |
email | string (email) | 0–320 chars |
identifier | object | object | — |
resend | boolean | — |
ref | string (uuid) | — |
Example
{
"kind": "student",
"email": "ada.lovelace@example.com",
"identifier": {
"email": "ada.lovelace@example.com"
},
"resend": true,
"ref": "42f48402-42f4-72f4-8f48-42f4840242f4"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/accounts/links" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"kind": "student",
"email": "ada.lovelace@example.com",
"identifier": {
"email": "ada.lovelace@example.com"
},
"resend": true,
"ref": "42f48402-42f4-72f4-8f48-42f4840242f4"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
kindrequired | enum: "student" | "guardian" | — |
statusrequired | enum: "invited" | "active" | "removed" | "declined" | — |
invitedAtrequired | string (date-time) | null | — |
activatedAtrequired | string (date-time) | null | — |
removedAtrequired | string (date-time) | null | — |
declinedAtrequired | string (date-time) | null | — |
inviteEmailSentAtrequired | string (date-time) | null | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"kind": "student",
"status": "invited",
"invitedAt": "2026-03-02T09:00:00.000Z",
"activatedAt": "2026-03-02T09:00:00.000Z",
"removedAt": "2026-03-02T09:00:00.000Z",
"declinedAt": "2026-03-02T09:00:00.000Z",
"inviteEmailSentAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/accounts/links/activate
The first successful Institflow-account sign-in into this institute (§2.5 step 3). Idempotent — activating an already-active link is a no-op.
Request body
| Name | Type | Constraints |
|---|---|---|
kindrequired | enum: "student" | "guardian" | — |
emailrequired | string (email) | 0–320 chars |
accountIdrequired | string (uuid) | — |
ensure | boolean | — |
Example
{
"kind": "student",
"email": "ada.lovelace@example.com",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"ensure": true
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/accounts/links/activate" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"kind": "student",
"email": "ada.lovelace@example.com",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"ensure": true
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
kindrequired | enum: "student" | "guardian" | — |
statusrequired | enum: "invited" | "active" | "removed" | "declined" | — |
invitedAtrequired | string (date-time) | null | — |
activatedAtrequired | string (date-time) | null | — |
removedAtrequired | string (date-time) | null | — |
declinedAtrequired | string (date-time) | null | — |
inviteEmailSentAtrequired | string (date-time) | null | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"kind": "student",
"status": "invited",
"invitedAt": "2026-03-02T09:00:00.000Z",
"activatedAt": "2026-03-02T09:00:00.000Z",
"removedAt": "2026-03-02T09:00:00.000Z",
"declinedAt": "2026-03-02T09:00:00.000Z",
"inviteEmailSentAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/accounts/links/decision
Tell the account that asked to join through a join link the owner's answer (`approved` or `rejected`): it is mailed. The account must own the `email` given.
Request body
| Name | Type | Constraints |
|---|---|---|
kindrequired | enum: "student" | "guardian" | — |
emailrequired | string (email) | 0–320 chars |
accountIdrequired | string (uuid) | — |
decisionrequired | enum: "approved" | "rejected" | — |
Example
{
"kind": "student",
"email": "ada.lovelace@example.com",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"decision": "approved"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/accounts/links/decision" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"kind": "student",
"email": "ada.lovelace@example.com",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"decision": "approved"
}'Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/accounts/links/responses
The answer to each of this install's own invitations (`ref` = the install's invitation id): `pending`, `accepted` or `declined`. A ref this install never made reads `pending`, like an open one.
Request body
| Name | Type | Constraints |
|---|---|---|
refsrequired | array<string (uuid)> | — |
Example
{
"refs": [
"d7ec7de3-d7ec-77ec-8ec7-d7ec7de3d7ec"
]
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/accounts/links/responses" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"refs": [
"d7ec7de3-d7ec-77ec-8ec7-d7ec7de3d7ec"
]
}'Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
{
"data": [
{
"ref": "42f48402-42f4-72f4-8f48-42f4840242f4",
"response": "pending"
}
]
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/admins
List platform admins: role, status, 2FA enrolment, last login.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/admins" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"userId": "11f967df-11f9-71f9-8f96-11f967df11f9",
"email": "ada.lovelace@example.com",
"fullName": "Ada Lovelace",
"role": "owner",
"status": "active",
"totpEnrolled": true,
"lastLoginAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
DELETE /api/v1/platform/admins/{userId}
Remove a platform admin (the user account itself is untouched). Owner only, cannot target yourself, cannot remove the last enabled owner.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
userIdrequired | path | string | — |
curl example
curl -X DELETE "https://your-institute.example/api/v1/platform/admins/11f967df-11f9-71f9-8f96-11f967df11f9" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
PATCH /api/v1/platform/admins/{userId}
Change a platform admin’s role. Owner only, cannot target yourself; requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
userIdrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
rolerequired | enum: "owner" | "support" | — |
Example
{
"role": "owner"
}curl example
curl -X PATCH "https://your-institute.example/api/v1/platform/admins/11f967df-11f9-71f9-8f96-11f967df11f9" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"role": "owner"
}'Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/admins/{userId}/disable
Disable a platform admin (revokes every session). Owner only, cannot target yourself, cannot disable the last enabled owner.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
userIdrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/admins/11f967df-11f9-71f9-8f96-11f967df11f9/disable" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/admins/{userId}/enable
Re-enable a disabled platform admin. Owner only; requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
userIdrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/admins/11f967df-11f9-71f9-8f96-11f967df11f9/enable" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/admins/{userId}/totp/reset
Reset a platform admin’s two-factor authentication for a lost device — they enrol again at next login. Owner only.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
userIdrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/admins/11f967df-11f9-71f9-8f96-11f967df11f9/totp/reset" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/admins/invitations
List every platform-admin invitation, pending or not.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/admins/invitations" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"email": "ada.lovelace@example.com",
"role": "owner",
"invitedBy": "27215cb9-2721-7721-8215-27215cb92721",
"expiresAt": "2026-03-02T09:00:00.000Z",
"acceptedAt": "2026-03-02T09:00:00.000Z",
"revokedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/admins/invitations
Invite a new platform admin by email. Owner only; requires a step-up MFA check within the last 10 minutes.
Request body
| Name | Type | Constraints |
|---|---|---|
emailrequired | string (email) | — |
rolerequired | enum: "owner" | "support" | — |
Example
{
"email": "ada.lovelace@example.com",
"role": "owner"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/admins/invitations" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"email": "ada.lovelace@example.com",
"role": "owner"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
emailrequired | string (email) | — |
rolerequired | enum: "owner" | "support" | — |
invitedByrequired | string (uuid) | — |
expiresAtrequired | string (date-time) | — |
acceptedAtrequired | string (date-time) | null | — |
revokedAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"email": "ada.lovelace@example.com",
"role": "owner",
"invitedBy": "27215cb9-2721-7721-8215-27215cb92721",
"expiresAt": "2026-03-02T09:00:00.000Z",
"acceptedAt": "2026-03-02T09:00:00.000Z",
"revokedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/admins/invitations/{id}/revoke
Revoke a still-pending platform-admin invitation. Owner only; requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/admins/invitations/37386ae0-3738-7738-8386-37386ae03738/revoke" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/customer-requests
List institute requests (cursor-paginated, optional status filter).
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
status | query | enum: "pending" | "approved" | "refused" | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/customer-requests" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"instituteName": "string",
"slug": "string",
"country": "string",
"sizeBand": "small",
"phone": "+15551234567",
"status": "pending",
"refusalReason": "string",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"requesterEmail": "ada.lovelace@example.com",
"decidedAt": "2026-03-02T09:00:00.000Z",
"decidedBy": "d4d316ba-d4d3-74d3-8d31-d4d316bad4d3"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/customer-requests/{id}
One institute request, with the requesting account’s email.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/customer-requests/37386ae0-3738-7738-8386-37386ae03738" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
instituteNamerequired | string | — |
slugrequired | string | — |
countryrequired | string | — |
sizeBandrequired | enum: "small" | "medium" | "large" | "xlarge" | — |
phonerequired | string | null | — |
statusrequired | enum: "pending" | "approved" | "refused" | — |
refusalReasonrequired | string | null | — |
tenantIdrequired | string (uuid) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
accountIdrequired | string (uuid) | — |
requesterEmailrequired | string (email) | — |
decidedAtrequired | string (date-time) | null | — |
decidedByrequired | string (uuid) | null | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"instituteName": "string",
"slug": "string",
"country": "string",
"sizeBand": "small",
"phone": "+15551234567",
"status": "pending",
"refusalReason": "string",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"requesterEmail": "ada.lovelace@example.com",
"decidedAt": "2026-03-02T09:00:00.000Z",
"decidedBy": "d4d316ba-d4d3-74d3-8d31-d4d316bad4d3"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/customer-requests/{id}/approve
Approve an institute request: creates the tenant (the "Add a customer" path), sets its owner, mails the requester. Owner only; requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
planCoderequired | string | 1–50 chars |
trialDays | integer | 0–365 |
Example
{
"planCode": "string",
"trialDays": 0
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/customer-requests/37386ae0-3738-7738-8386-37386ae03738/approve" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"planCode": "string",
"trialDays": 0
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
instituteNamerequired | string | — |
slugrequired | string | — |
countryrequired | string | — |
sizeBandrequired | enum: "small" | "medium" | "large" | "xlarge" | — |
phonerequired | string | null | — |
statusrequired | enum: "pending" | "approved" | "refused" | — |
refusalReasonrequired | string | null | — |
tenantIdrequired | string (uuid) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
accountIdrequired | string (uuid) | — |
requesterEmailrequired | string (email) | — |
decidedAtrequired | string (date-time) | null | — |
decidedByrequired | string (uuid) | null | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"instituteName": "string",
"slug": "string",
"country": "string",
"sizeBand": "small",
"phone": "+15551234567",
"status": "pending",
"refusalReason": "string",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"requesterEmail": "ada.lovelace@example.com",
"decidedAt": "2026-03-02T09:00:00.000Z",
"decidedBy": "d4d316ba-d4d3-74d3-8d31-d4d316bad4d3"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/customer-requests/{id}/refuse
Refuse an institute request with a reason, mailed to the requester. Owner only; requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
reasonrequired | string | 1–2000 chars |
Example
{
"reason": "Requested by guardian."
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/customer-requests/37386ae0-3738-7738-8386-37386ae03738/refuse" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"reason": "Requested by guardian."
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
instituteNamerequired | string | — |
slugrequired | string | — |
countryrequired | string | — |
sizeBandrequired | enum: "small" | "medium" | "large" | "xlarge" | — |
phonerequired | string | null | — |
statusrequired | enum: "pending" | "approved" | "refused" | — |
refusalReasonrequired | string | null | — |
tenantIdrequired | string (uuid) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
accountIdrequired | string (uuid) | — |
requesterEmailrequired | string (email) | — |
decidedAtrequired | string (date-time) | null | — |
decidedByrequired | string (uuid) | null | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"instituteName": "string",
"slug": "string",
"country": "string",
"sizeBand": "small",
"phone": "+15551234567",
"status": "pending",
"refusalReason": "string",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"requesterEmail": "ada.lovelace@example.com",
"decidedAt": "2026-03-02T09:00:00.000Z",
"decidedBy": "d4d316ba-d4d3-74d3-8d31-d4d316bad4d3"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/installs
Fleet-wide list of self-hosted installs: institute, version, last heartbeat, updater result, relay install state (cursor-paginated).
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/installs" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"licenseId": "f5f084e9-f5f0-75f0-8f08-f5f084e9f5f0",
"installId": "2472867d-2472-7472-8728-2472867d2472",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"tenantName": "string",
"tenantSlug": "string",
"appVersion": "string",
"lastSeenAt": "2026-03-02T09:00:00.000Z",
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"updateChannel": "stable",
"updaterLastCheckAt": "2026-03-02T09:00:00.000Z",
"updaterLastResult": "up_to_date",
"updaterLastReason": "none",
"backup": {
"lastStatus": "success",
"lastRunAt": "2026-03-02T09:00:00.000Z",
"lastSuccessAt": "2026-03-02T09:00:00.000Z"
},
"guardian": {
"version": 1,
"updaterVersion": "string",
"lastTickAt": "2026-03-02T09:00:00.000Z"
},
"needsAdoption": true,
"relayInstallStatus": "approved",
"address": "string",
"serverIp": "string",
"state": "provisioning"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/installs/{id}/dns
Restore this install's DNS A record (docs/specs/phase12-one-step-install.md §2.5). Refused for a non-active customer, an own-domain install, or one with no stored address.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/installs/37386ae0-3738-7738-8386-37386ae03738/dns" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
licenseIdrequired | string (uuid) | — |
installIdrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
tenantNamerequired | string | — |
tenantSlugrequired | string | — |
appVersionrequired | string | null | — |
lastSeenAtrequired | string (date-time) | null | — |
firstSeenAtrequired | string (date-time) | — |
updateChannelrequired | enum: "stable" | "beta" | null | null | — |
updaterLastCheckAtrequired | string (date-time) | null | — |
updaterLastResultrequired | enum: "up_to_date" | "updated" | "rolled_back" | "failed" | "skipped" | null | null | — |
updaterLastReasonrequired | 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 | — |
backuprequired | object | null | — |
guardianrequired | object | null | — |
needsAdoptionrequired | boolean | — |
relayInstallStatusrequired | enum: "approved" | "pending" | "blocked" | null | null | — |
addressrequired | string | null | — |
serverIprequired | string | null | — |
staterequired | enum: "provisioning" | "running" | "unreachable" | null | null | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"licenseId": "f5f084e9-f5f0-75f0-8f08-f5f084e9f5f0",
"installId": "2472867d-2472-7472-8728-2472867d2472",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"tenantName": "string",
"tenantSlug": "string",
"appVersion": "string",
"lastSeenAt": "2026-03-02T09:00:00.000Z",
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"updateChannel": "stable",
"updaterLastCheckAt": "2026-03-02T09:00:00.000Z",
"updaterLastResult": "up_to_date",
"updaterLastReason": "none",
"backup": {
"lastStatus": "success",
"lastRunAt": "2026-03-02T09:00:00.000Z",
"lastSuccessAt": "2026-03-02T09:00:00.000Z"
},
"guardian": {
"version": 1,
"updaterVersion": "string",
"lastTickAt": "2026-03-02T09:00:00.000Z"
},
"needsAdoption": true,
"relayInstallStatus": "approved",
"address": "string",
"serverIp": "string",
"state": "provisioning"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/licenses/{licenseId}/installs
Installs seen on this license, with last-seen, version, tamper signals and pending commands.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
licenseIdrequired | path | string | — |
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/licenses/f5f084e9-f5f0-75f0-8f08-f5f084e9f5f0/installs" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"licenseId": "f5f084e9-f5f0-75f0-8f08-f5f084e9f5f0",
"installId": "2472867d-2472-7472-8728-2472867d2472",
"appVersion": "string",
"lastSeenAt": "2026-03-02T09:00:00.000Z",
"heartbeatCounter": 0,
"signals": [
{
"kind": "silent",
"severity": "info",
"detectedAt": "2026-03-02T09:00:00.000Z",
"detail": "string"
}
],
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"lastWitnessAt": "2026-03-02T09:00:00.000Z",
"updateChannel": "stable",
"updaterLastCheckAt": "2026-03-02T09:00:00.000Z",
"updaterLastResult": "up_to_date",
"updaterLastReason": "none",
"pendingCommands": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"kind": "lock",
"reason": "Requested by guardian.",
"issuedAt": "2026-03-02T09:00:00.000Z"
}
]
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/licenses/{licenseId}/lock
Lock a self-hosted install: issues a signed lock command applied on its next heartbeat.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
licenseIdrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
reasonrequired | string | 1–500 chars |
Example
{
"reason": "Requested by guardian."
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/licenses/f5f084e9-f5f0-75f0-8f08-f5f084e9f5f0/lock" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"reason": "Requested by guardian."
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
licenseIdrequired | string (uuid) | — |
kindrequired | enum: "lock" | "unlock" | — |
reasonrequired | string | null | — |
issuedAtrequired | string (date-time) | — |
acknowledgedAtrequired | string (date-time) | null | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"licenseId": "f5f084e9-f5f0-75f0-8f08-f5f084e9f5f0",
"kind": "lock",
"reason": "Requested by guardian.",
"issuedAt": "2026-03-02T09:00:00.000Z",
"acknowledgedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/licenses/{licenseId}/unlock
Unlock a self-hosted install: issues a signed unlock command.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
licenseIdrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/licenses/f5f084e9-f5f0-75f0-8f08-f5f084e9f5f0/unlock" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
licenseIdrequired | string (uuid) | — |
kindrequired | enum: "lock" | "unlock" | — |
reasonrequired | string | null | — |
issuedAtrequired | string (date-time) | — |
acknowledgedAtrequired | string (date-time) | null | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"licenseId": "f5f084e9-f5f0-75f0-8f08-f5f084e9f5f0",
"kind": "lock",
"reason": "Requested by guardian.",
"issuedAt": "2026-03-02T09:00:00.000Z",
"acknowledgedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/licenses/{licenseId}/unlock-token
Mint a one-time signed unlock token the customer pastes into their self-hosted admin when the license server is unreachable.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
licenseIdrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/licenses/f5f084e9-f5f0-75f0-8f08-f5f084e9f5f0/unlock-token" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
tokenrequired | string | — |
expiresAtrequired | string (date-time) | — |
{
"token": "string",
"expiresAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/licenses/heartbeat
Self-hosted install heartbeat, signed with the relay identity. Returns a signed envelope carrying server time, state, and any pending lock/unlock commands.
Request body
| Name | Type | Constraints |
|---|---|---|
jtirequired | string | 1–200 chars |
appVersionrequired | string | 1–50 chars |
counterrequired | integer | 0–9007199254740991 |
clientTimerequired | string (date-time) | — |
maxObservedTimerequired | string (date-time) | null | — |
noncerequired | string | 1–100 chars |
appliedCommandIds | array<string (uuid)> | default: [] |
updater | object | — |
backup | object | — |
guardian | object | — |
Example
{
"jti": "string",
"appVersion": "string",
"counter": 0,
"clientTime": "2026-03-02T09:00:00.000Z",
"maxObservedTime": "2026-03-02T09:00:00.000Z",
"nonce": "string",
"appliedCommandIds": [
"3a42c45f-3a42-7a42-842c-3a42c45f3a42"
],
"updater": {
"lastCheckAt": "2026-03-02T09:00:00.000Z",
"lastResult": "up_to_date",
"reason": "none",
"channel": "stable"
},
"backup": {
"lastStatus": "success",
"lastRunAt": "2026-03-02T09:00:00.000Z",
"lastSuccessAt": "2026-03-02T09:00:00.000Z"
},
"guardian": {
"version": 1,
"updaterVersion": "string",
"lastTickAt": "2026-03-02T09:00:00.000Z"
}
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/licenses/heartbeat" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"jti": "string",
"appVersion": "string",
"counter": 0,
"clientTime": "2026-03-02T09:00:00.000Z",
"maxObservedTime": "2026-03-02T09:00:00.000Z",
"nonce": "string",
"appliedCommandIds": [
"3a42c45f-3a42-7a42-842c-3a42c45f3a42"
],
"updater": {
"lastCheckAt": "2026-03-02T09:00:00.000Z",
"lastResult": "up_to_date",
"reason": "none",
"channel": "stable"
},
"backup": {
"lastStatus": "success",
"lastRunAt": "2026-03-02T09:00:00.000Z",
"lastSuccessAt": "2026-03-02T09:00:00.000Z"
},
"guardian": {
"version": 1,
"updaterVersion": "string",
"lastTickAt": "2026-03-02T09:00:00.000Z"
}
}'Responses
| Name | Type | Constraints |
|---|---|---|
enveloperequired | string | — |
{
"envelope": "string"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/licenses/releases/manifest
The signed release manifest for a channel. Verified against the license public key baked into every self-hosted image.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
channel | query | enum: "stable" | "beta" | default: "stable" |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/licenses/releases/manifest" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
manifestrequired | string | — |
payloadrequired | object | — |
{
"manifest": "string",
"payload": {
"channel": "stable",
"version": "string",
"images": {
"api": {
"ref": "string",
"digest": "string"
},
"web": {
"ref": "string",
"digest": "string"
}
},
"minFromVersion": "string",
"migrations": "forward-only",
"releasedAt": "2026-03-02T09:00:00.000Z",
"notes": "Prefers afternoon sessions."
}
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/licenses/releases/v2/manifest
The signed release manifest, version 2 (updater and backup images, desired-state sha256, repair mode), for a channel.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
channel | query | enum: "stable" | "beta" | default: "stable" |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/licenses/releases/v2/manifest" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
manifestrequired | string | — |
payloadrequired | object | — |
{
"manifest": "string",
"payload": {
"schema": 2,
"channel": "stable",
"version": "string",
"images": {
"api": {
"ref": "string",
"digest": "string"
},
"web": {
"ref": "string",
"digest": "string"
},
"backup": {
"ref": "string",
"digest": "string"
},
"updater": {
"ref": "string",
"digest": "string"
}
},
"desiredState": {
"sha256": "string",
"updaterProtocol": 1
},
"repairMode": "repair",
"offsite": {
"uploadHosts": [
"string"
]
},
"minFromVersion": "string",
"migrations": "forward-only",
"releasedAt": "2026-03-02T09:00:00.000Z",
"notes": "Prefers afternoon sessions."
}
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/licenses/releases/v2/manifest/{version}
The signed v2 manifest of one published version.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
versionrequired | path | string | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/licenses/releases/v2/manifest/string" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
manifestrequired | string | — |
payloadrequired | object | — |
{
"manifest": "string",
"payload": {
"schema": 2,
"channel": "stable",
"version": "string",
"images": {
"api": {
"ref": "string",
"digest": "string"
},
"web": {
"ref": "string",
"digest": "string"
},
"backup": {
"ref": "string",
"digest": "string"
},
"updater": {
"ref": "string",
"digest": "string"
}
},
"desiredState": {
"sha256": "string",
"updaterProtocol": 1
},
"repairMode": "repair",
"offsite": {
"uploadHosts": [
"string"
]
},
"minFromVersion": "string",
"migrations": "forward-only",
"releasedAt": "2026-03-02T09:00:00.000Z",
"notes": "Prefers afternoon sessions."
}
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/login-discovery
Resolve an email to every host it can sign in on (platform admin / Institflow account / institute install) — identical response shape whether the email is known or not.
Request body
| Name | Type | Constraints |
|---|---|---|
emailrequired | string (email) | 0–320 chars |
Example
{
"email": "ada.lovelace@example.com"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/login-discovery" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"email": "ada.lovelace@example.com"
}'Responses
| Name | Type | Constraints |
|---|---|---|
outcomesrequired | array<unknown> | — |
{
"outcomes": [
"value"
]
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/me
The current platform admin’s profile, 2FA status and session count.
curl example
curl -X GET "https://your-institute.example/api/v1/platform/me" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
userIdrequired | string (uuid) | — |
emailrequired | string (email) | — |
pendingEmailrequired | string (email) | null | — |
fullNamerequired | string | — |
localerequired | enum: "ar" | "en" | "he" | — |
rolerequired | enum: "owner" | "support" | — |
totpEnrolledrequired | boolean | — |
sessionCountrequired | integer | -9007199254740991–9007199254740991 |
{
"userId": "11f967df-11f9-71f9-8f96-11f967df11f9",
"email": "ada.lovelace@example.com",
"pendingEmail": "ada.lovelace@example.com",
"fullName": "Ada Lovelace",
"locale": "ar",
"role": "owner",
"totpEnrolled": true,
"sessionCount": -9007199254740991
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/me/change-email
Request an email change — sends a confirmation link to the NEW address. Requires the current password and a step-up MFA check within the last 10 minutes.
Request body
| Name | Type | Constraints |
|---|---|---|
newEmailrequired | string (email) | — |
currentPasswordrequired | string | ≥1 chars |
Example
{
"newEmail": "ada.lovelace@example.com",
"currentPassword": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/me/change-email" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"newEmail": "ada.lovelace@example.com",
"currentPassword": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/me/change-password
Change your own password. Revokes every OTHER session (this one stays signed in).
Request body
| Name | Type | Constraints |
|---|---|---|
currentPasswordrequired | string | ≥1 chars |
newPasswordrequired | string | ≥10 chars |
Example
{
"currentPassword": "string",
"newPassword": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/me/change-password" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"currentPassword": "string",
"newPassword": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/me/confirm-email
Confirm a pending email change from the link sent to the new address.
Request body
| Name | Type | Constraints |
|---|---|---|
tokenrequired | string | ≥1 chars |
Example
{
"token": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/me/confirm-email" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"token": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/me/sessions
Every active session for the current platform admin.
curl example
curl -X GET "https://your-institute.example/api/v1/platform/me/sessions" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
[
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"userAgent": "string",
"ip": "string",
"lastUsedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"mfaAt": "2026-03-02T09:00:00.000Z"
}
]Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
DELETE /api/v1/platform/me/sessions/{id}
Revoke one of your own sessions.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X DELETE "https://your-institute.example/api/v1/platform/me/sessions/37386ae0-3738-7738-8386-37386ae03738" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/me/totp/enable
Complete TOTP enrolment with a live code from the app. This *is* the login the mfa/enroll challenge stood in for: returns the real token pair, plus 10 recovery codes shown exactly once.
Request body
| Name | Type | Constraints |
|---|---|---|
coderequired | string | — |
client | enum: "web" | "mobile" | default: "web" |
Example
{
"code": "string",
"client": "web"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/me/totp/enable" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"code": "string",
"client": "web"
}'Responses
| Name | Type | Constraints |
|---|---|---|
accessTokenrequired | string | — |
refreshToken | string | — |
userrequired | object | — |
membershipsrequired | array<MembershipSummary> | — |
activeTenantIdrequired | string (uuid) | null | — |
recoveryCodesrequired | array<string> | — |
{
"accessToken": "string",
"refreshToken": "string",
"user": {
"id": "37386ae0-3738-7738-8386-37386ae03738",
"email": "ada.lovelace@example.com",
"fullName": "Ada Lovelace",
"locale": "ar",
"status": "active",
"emailVerified": true
},
"memberships": [
{
"membershipId": "e34c26d7-e34c-734c-84c2-e34c26d7e34c",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"tenantSlug": "string",
"tenantName": "string",
"status": "invited",
"roles": [
{
"roleId": "5b007a17-5b00-7b00-8007-5b007a175b00",
"roleName": "string",
"roleKey": "string"
}
]
}
],
"activeTenantId": "f056e4d2-f056-7056-856e-f056e4d2f056",
"recoveryCodes": [
"string"
]
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/me/totp/regenerate-recovery-codes
Replace every recovery code. Requires a live TOTP code (re-authenticates in place of a step-up).
Request body
| Name | Type | Constraints |
|---|---|---|
coderequired | string | — |
Example
{
"code": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/me/totp/regenerate-recovery-codes" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"code": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
recoveryCodesrequired | array<string> | — |
{
"recoveryCodes": [
"string"
]
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/me/totp/setup
Begin TOTP enrolment: returns the otpauth:// URI + secret (shown once). Refused once 2FA is already enabled.
curl example
curl -X POST "https://your-institute.example/api/v1/platform/me/totp/setup" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
otpauthUrirequired | string | — |
secretBase32required | string | — |
{
"otpauthUri": "string",
"secretBase32": "string"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
curl example
curl -X GET "https://your-institute.example/api/v1/platform/plans" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
[
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"code": "string",
"name": "Algebra I",
"priceMinor": 12000,
"currency": "USD",
"billingInterval": "month",
"limits": {
"maxStudents": -9007199254740991,
"maxBranches": -9007199254740991,
"maxVideoCourses": -9007199254740991,
"maxLessonsPerCourse": -9007199254740991,
"notificationQuota": {
"whatsapp": -9007199254740991,
"sms": -9007199254740991,
"email": "ada.lovelace@example.com"
}
},
"features": [
"string"
],
"isActive": true,
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}
]Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Request body
| Name | Type | Constraints |
|---|---|---|
coderequired | string | 1–50 chars |
namerequired | string | 1–200 chars |
priceMinorrequired | integer | 0–9007199254740991 |
currencyrequired | string | 3–3 chars |
billingIntervalrequired | enum: "month" | "year" | — |
limitsrequired | object | — |
featuresrequired | array<string> | — |
Example
{
"code": "string",
"name": "Algebra I",
"priceMinor": 12000,
"currency": "USD",
"billingInterval": "month",
"limits": {
"maxStudents": 0,
"maxBranches": 0,
"maxVideoCourses": -1,
"maxLessonsPerCourse": -1,
"notificationQuota": {
"whatsapp": 0,
"sms": 0,
"email": "ada.lovelace@example.com"
}
},
"features": [
"string"
]
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/plans" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"code": "string",
"name": "Algebra I",
"priceMinor": 12000,
"currency": "USD",
"billingInterval": "month",
"limits": {
"maxStudents": 0,
"maxBranches": 0,
"maxVideoCourses": -1,
"maxLessonsPerCourse": -1,
"notificationQuota": {
"whatsapp": 0,
"sms": 0,
"email": "ada.lovelace@example.com"
}
},
"features": [
"string"
]
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
coderequired | string | — |
namerequired | string | — |
priceMinorrequired | integer | -9007199254740991–9007199254740991 |
currencyrequired | string | 3–3 chars |
billingIntervalrequired | enum: "month" | "year" | — |
limitsrequired | PlanLimits | — |
featuresrequired | array<string> | — |
isActiverequired | boolean | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"code": "string",
"name": "Algebra I",
"priceMinor": 12000,
"currency": "USD",
"billingInterval": "month",
"limits": {
"maxStudents": -9007199254740991,
"maxBranches": -9007199254740991,
"maxVideoCourses": -9007199254740991,
"maxLessonsPerCourse": -9007199254740991,
"notificationQuota": {
"whatsapp": -9007199254740991,
"sms": -9007199254740991,
"email": "ada.lovelace@example.com"
}
},
"features": [
"string"
],
"isActive": true,
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
PATCH /api/v1/platform/plans/{id}
Update a plan (use `isActive: false` to deactivate — plans are never deleted).
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
name | string | 1–200 chars |
priceMinor | integer | 0–9007199254740991 |
currency | string | 3–3 chars |
billingInterval | enum: "month" | "year" | — |
limits | object | — |
features | array<string> | — |
isActive | boolean | — |
Example
{
"name": "Algebra I",
"priceMinor": 12000,
"currency": "USD",
"billingInterval": "month",
"limits": {
"maxStudents": 0,
"maxBranches": 0,
"maxVideoCourses": -1,
"maxLessonsPerCourse": -1,
"notificationQuota": {
"whatsapp": 0,
"sms": 0,
"email": "ada.lovelace@example.com"
}
},
"features": [
"string"
],
"isActive": true
}curl example
curl -X PATCH "https://your-institute.example/api/v1/platform/plans/37386ae0-3738-7738-8386-37386ae03738" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Algebra I",
"priceMinor": 12000,
"currency": "USD",
"billingInterval": "month",
"limits": {
"maxStudents": 0,
"maxBranches": 0,
"maxVideoCourses": -1,
"maxLessonsPerCourse": -1,
"notificationQuota": {
"whatsapp": 0,
"sms": 0,
"email": "ada.lovelace@example.com"
}
},
"features": [
"string"
],
"isActive": true
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
coderequired | string | — |
namerequired | string | — |
priceMinorrequired | integer | -9007199254740991–9007199254740991 |
currencyrequired | string | 3–3 chars |
billingIntervalrequired | enum: "month" | "year" | — |
limitsrequired | PlanLimits | — |
featuresrequired | array<string> | — |
isActiverequired | boolean | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"code": "string",
"name": "Algebra I",
"priceMinor": 12000,
"currency": "USD",
"billingInterval": "month",
"limits": {
"maxStudents": -9007199254740991,
"maxBranches": -9007199254740991,
"maxVideoCourses": -9007199254740991,
"maxLessonsPerCourse": -9007199254740991,
"notificationQuota": {
"whatsapp": -9007199254740991,
"sms": -9007199254740991,
"email": "ada.lovelace@example.com"
}
},
"features": [
"string"
],
"isActive": true,
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/queues
Job counts (waiting/active/failed/delayed) per BullMQ queue (docs/ARCHITECTURE.md §4.7).
curl example
curl -X GET "https://your-institute.example/api/v1/platform/queues" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
maintenancerequired | QueueJobCounts | — |
notificationsrequired | QueueJobCounts | — |
webhooksrequired | QueueJobCounts | — |
reportsrequired | QueueJobCounts | — |
digestrequired | QueueJobCounts | — |
billingrequired | QueueJobCounts | — |
academicsrequired | QueueJobCounts | — |
remindersrequired | QueueJobCounts | — |
relay-system-mailrequired | QueueJobCounts | — |
account-links-syncrequired | QueueJobCounts | — |
support-submissionsrequired | QueueJobCounts | — |
{
"maintenance": {
"waiting": -9007199254740991,
"active": -9007199254740991,
"failed": -9007199254740991,
"delayed": -9007199254740991
},
"notifications": {
"waiting": -9007199254740991,
"active": -9007199254740991,
"failed": -9007199254740991,
"delayed": -9007199254740991
},
"webhooks": {
"waiting": -9007199254740991,
"active": -9007199254740991,
"failed": -9007199254740991,
"delayed": -9007199254740991
},
"reports": {
"waiting": -9007199254740991,
"active": -9007199254740991,
"failed": -9007199254740991,
"delayed": -9007199254740991
},
"digest": {
"waiting": -9007199254740991,
"active": -9007199254740991,
"failed": -9007199254740991,
"delayed": -9007199254740991
},
"billing": {
"waiting": -9007199254740991,
"active": -9007199254740991,
"failed": -9007199254740991,
"delayed": -9007199254740991
},
"academics": {
"waiting": -9007199254740991,
"active": -9007199254740991,
"failed": -9007199254740991,
"delayed": -9007199254740991
},
"reminders": {
"waiting": -9007199254740991,
"active": -9007199254740991,
"failed": -9007199254740991,
"delayed": -9007199254740991
},
"relay-system-mail": {
"waiting": -9007199254740991,
"active": -9007199254740991,
"failed": -9007199254740991,
"delayed": -9007199254740991
},
"account-links-sync": {
"waiting": -9007199254740991,
"active": -9007199254740991,
"failed": -9007199254740991,
"delayed": -9007199254740991
},
"support-submissions": {
"waiting": -9007199254740991,
"active": -9007199254740991,
"failed": -9007199254740991,
"delayed": -9007199254740991
}
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/registry/token
Docker Registry v2 token endpoint. HTTP Basic credentials (a registry_credentials row, or the vendor release identity); scope/service per the Docker Registry v2 token spec.
curl example
curl -X GET "https://your-institute.example/api/v1/platform/registry/token" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
tokenrequired | string | — |
access_tokenrequired | string | — |
{
"token": "string",
"access_token": "string"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/relay/account
This install's account snapshot: balance, overdraft, prices in force, install status.
curl example
curl -X GET "https://your-institute.example/api/v1/platform/relay/account" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
balanceUnitsrequired | integer | -9007199254740991–9007199254740991 |
overdraftUnitsrequired | integer | -9007199254740991–9007199254740991 |
statusrequired | enum: "active" | "closed" | — |
reputationHoldrequired | boolean | — |
relayEmailEnabledrequired | boolean | — |
installStatusrequired | enum: "approved" | "pending" | "blocked" | — |
pricesrequired | array<object> | — |
senderNamerequired | object | — |
{
"balanceUnits": -9007199254740991,
"overdraftUnits": -9007199254740991,
"status": "active",
"reputationHold": true,
"relayEmailEnabled": true,
"installStatus": "approved",
"prices": [
{
"senderMode": "platform",
"priceUnits": -9007199254740991
}
],
"senderName": {
"displayName": "string",
"state": "none"
}
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/relay/account/sender-name
Submit this install’s requested institute-mode display name for the owner’s one-time impersonation-check approval (§11.3).
Request body
| Name | Type | Constraints |
|---|---|---|
displayNamerequired | string | 1–70 chars |
Example
{
"displayName": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/relay/account/sender-name" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"displayName": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/relay/accounts
List relay accounts: balance, overdraft, 30-day spend, and the owning tenant’s name/slug.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/relay/accounts" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"balanceUnits": -9007199254740991,
"overdraftUnits": -9007199254740991,
"status": "active",
"ratePerMinute": -9007199254740991,
"ratePerDay": -9007199254740991,
"reputationHold": true,
"reputationHoldReason": "string",
"senderDisplayName": "string",
"senderNameApprovedAt": "2026-03-02T09:00:00.000Z",
"senderNameRequestedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z",
"spend30dUnits": -9007199254740991,
"installCount": -9007199254740991,
"pendingInstallCount": -9007199254740991,
"tenantSlug": "string",
"tenantName": "string"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/relay/accounts/{tenantId}
A single tenant’s relay account, with its 30-day spend.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/relay/accounts/4332af8b-4332-7332-832a-4332af8b4332" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
balanceUnitsrequired | integer | -9007199254740991–9007199254740991 |
overdraftUnitsrequired | integer | -9007199254740991–9007199254740991 |
statusrequired | enum: "active" | "closed" | — |
ratePerMinuterequired | integer | null | -9007199254740991–9007199254740991 |
ratePerDayrequired | integer | null | -9007199254740991–9007199254740991 |
reputationHoldrequired | boolean | — |
reputationHoldReasonrequired | string | null | — |
senderDisplayNamerequired | string | null | — |
senderNameApprovedAtrequired | string (date-time) | null | — |
senderNameRequestedAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
spend30dUnitsrequired | integer | -9007199254740991–9007199254740991 |
installCountrequired | integer | -9007199254740991–9007199254740991 |
pendingInstallCountrequired | integer | -9007199254740991–9007199254740991 |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"balanceUnits": -9007199254740991,
"overdraftUnits": -9007199254740991,
"status": "active",
"ratePerMinute": -9007199254740991,
"ratePerDay": -9007199254740991,
"reputationHold": true,
"reputationHoldReason": "string",
"senderDisplayName": "string",
"senderNameApprovedAt": "2026-03-02T09:00:00.000Z",
"senderNameRequestedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z",
"spend30dUnits": -9007199254740991,
"installCount": -9007199254740991,
"pendingInstallCount": -9007199254740991
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
PATCH /api/v1/platform/relay/accounts/{tenantId}
Change a relay account’s overdraft limit, per-channel rate limits or reputation hold. Owner only; requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
overdraftUnits | integer | 0–9007199254740991 |
ratePerMinute | integer | null | ≤9007199254740991 |
ratePerDay | integer | null | ≤9007199254740991 |
reputationHold | boolean | — |
reputationHoldReason | string | null | 1–500 chars |
senderNameApproved | boolean | — |
Example
{
"overdraftUnits": 0,
"ratePerMinute": 1,
"ratePerDay": 1,
"reputationHold": true,
"reputationHoldReason": "string",
"senderNameApproved": true
}curl example
curl -X PATCH "https://your-institute.example/api/v1/platform/relay/accounts/4332af8b-4332-7332-832a-4332af8b4332" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"overdraftUnits": 0,
"ratePerMinute": 1,
"ratePerDay": 1,
"reputationHold": true,
"reputationHoldReason": "string",
"senderNameApproved": true
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
balanceUnitsrequired | integer | -9007199254740991–9007199254740991 |
overdraftUnitsrequired | integer | -9007199254740991–9007199254740991 |
statusrequired | enum: "active" | "closed" | — |
ratePerMinuterequired | integer | null | -9007199254740991–9007199254740991 |
ratePerDayrequired | integer | null | -9007199254740991–9007199254740991 |
reputationHoldrequired | boolean | — |
reputationHoldReasonrequired | string | null | — |
senderDisplayNamerequired | string | null | — |
senderNameApprovedAtrequired | string (date-time) | null | — |
senderNameRequestedAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"balanceUnits": -9007199254740991,
"overdraftUnits": -9007199254740991,
"status": "active",
"ratePerMinute": -9007199254740991,
"ratePerDay": -9007199254740991,
"reputationHold": true,
"reputationHoldReason": "string",
"senderDisplayName": "string",
"senderNameApprovedAt": "2026-03-02T09:00:00.000Z",
"senderNameRequestedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/relay/accounts/{tenantId}/adjustments
Record a manual balance correction (either sign, reason mandatory). Owner only; requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
amountUnitsrequired | integer | -9007199254740991–9007199254740991 |
reasonrequired | string | 1–500 chars |
note | string | 0–2000 chars |
Example
{
"amountUnits": -9007199254740991,
"reason": "Requested by guardian.",
"note": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/relay/accounts/4332af8b-4332-7332-832a-4332af8b4332/adjustments" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"amountUnits": -9007199254740991,
"reason": "Requested by guardian.",
"note": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
accountIdrequired | string (uuid) | — |
kindrequired | enum: "topup" | "debit" | "refund" | "adjustment" | — |
amountUnitsrequired | integer | -9007199254740991–9007199254740991 |
balanceAfterUnitsrequired | integer | -9007199254740991–9007199254740991 |
messageIdrequired | string (uuid) | null | — |
priceIdrequired | string (uuid) | null | — |
reasonrequired | string | null | — |
noterequired | string | null | — |
actorUserIdrequired | string (uuid) | null | — |
createdAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"kind": "topup",
"amountUnits": -9007199254740991,
"balanceAfterUnits": -9007199254740991,
"messageId": "1ac1c849-1ac1-7ac1-8c1c-1ac1c8491ac1",
"priceId": "48d77787-48d7-78d7-8d77-48d7778748d7",
"reason": "Requested by guardian.",
"note": "string",
"actorUserId": "7d892c08-7d89-7d89-8892-7d892c087d89",
"createdAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/relay/accounts/{tenantId}/ledger
The tenant’s relay ledger, newest first.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/relay/accounts/4332af8b-4332-7332-832a-4332af8b4332/ledger" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"kind": "topup",
"amountUnits": -9007199254740991,
"balanceAfterUnits": -9007199254740991,
"messageId": "1ac1c849-1ac1-7ac1-8c1c-1ac1c8491ac1",
"priceId": "48d77787-48d7-78d7-8d77-48d7778748d7",
"reason": "Requested by guardian.",
"note": "string",
"actorUserId": "7d892c08-7d89-7d89-8892-7d892c087d89",
"createdAt": "2026-03-02T09:00:00.000Z"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/relay/accounts/{tenantId}/sender-name/approve
Approve this account’s pending sender-name request, after the owner’s own impersonation check. The body must carry the exact displayName the console rendered — 409 CONFLICT if the install changed it since (TOCTOU guard, H3). Owner only, audited. Requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
displayNamerequired | string | 1–70 chars |
Example
{
"displayName": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/relay/accounts/4332af8b-4332-7332-832a-4332af8b4332/sender-name/approve" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"displayName": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
balanceUnitsrequired | integer | -9007199254740991–9007199254740991 |
overdraftUnitsrequired | integer | -9007199254740991–9007199254740991 |
statusrequired | enum: "active" | "closed" | — |
ratePerMinuterequired | integer | null | -9007199254740991–9007199254740991 |
ratePerDayrequired | integer | null | -9007199254740991–9007199254740991 |
reputationHoldrequired | boolean | — |
reputationHoldReasonrequired | string | null | — |
senderDisplayNamerequired | string | null | — |
senderNameApprovedAtrequired | string (date-time) | null | — |
senderNameRequestedAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"balanceUnits": -9007199254740991,
"overdraftUnits": -9007199254740991,
"status": "active",
"ratePerMinute": -9007199254740991,
"ratePerDay": -9007199254740991,
"reputationHold": true,
"reputationHoldReason": "string",
"senderDisplayName": "string",
"senderNameApprovedAt": "2026-03-02T09:00:00.000Z",
"senderNameRequestedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/relay/accounts/{tenantId}/sender-name/reject
Reject this account’s pending sender-name request — clears the requested name so the institute goes back to "none". The body must carry the exact displayName the console rendered — 409 CONFLICT if the install changed it since (TOCTOU guard, H3). Owner only, audited. Requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
displayNamerequired | string | 1–70 chars |
Example
{
"displayName": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/relay/accounts/4332af8b-4332-7332-832a-4332af8b4332/sender-name/reject" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"displayName": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
balanceUnitsrequired | integer | -9007199254740991–9007199254740991 |
overdraftUnitsrequired | integer | -9007199254740991–9007199254740991 |
statusrequired | enum: "active" | "closed" | — |
ratePerMinuterequired | integer | null | -9007199254740991–9007199254740991 |
ratePerDayrequired | integer | null | -9007199254740991–9007199254740991 |
reputationHoldrequired | boolean | — |
reputationHoldReasonrequired | string | null | — |
senderDisplayNamerequired | string | null | — |
senderNameApprovedAtrequired | string (date-time) | null | — |
senderNameRequestedAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"balanceUnits": -9007199254740991,
"overdraftUnits": -9007199254740991,
"status": "active",
"ratePerMinute": -9007199254740991,
"ratePerDay": -9007199254740991,
"reputationHold": true,
"reputationHoldReason": "string",
"senderDisplayName": "string",
"senderNameApprovedAt": "2026-03-02T09:00:00.000Z",
"senderNameRequestedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/relay/accounts/{tenantId}/suppressions
The tenant’s suppressed recipients (hashed, never readable), newest first.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/relay/accounts/4332af8b-4332-7332-832a-4332af8b4332/suppressions" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"recipientHash": "string",
"reason": "Requested by guardian.",
"createdAt": "2026-03-02T09:00:00.000Z"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
DELETE /api/v1/platform/relay/accounts/{tenantId}/suppressions/{id}
Lift a suppression so the relay may send to this recipient again. Owner only, audited. Requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
idrequired | path | string | — |
curl example
curl -X DELETE "https://your-institute.example/api/v1/platform/relay/accounts/4332af8b-4332-7332-832a-4332af8b4332/suppressions/37386ae0-3738-7738-8386-37386ae03738" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/relay/accounts/{tenantId}/top-ups
Record a hand-received top-up (e.g. cash) to a tenant’s relay balance. Owner only; not idempotent by design — a repeated call records a second row (§11.4). Requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
amountUnitsrequired | integer | 0–9007199254740991 |
reasonrequired | string | 1–500 chars |
note | string | 0–2000 chars |
Example
{
"amountUnits": 0,
"reason": "Requested by guardian.",
"note": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/relay/accounts/4332af8b-4332-7332-832a-4332af8b4332/top-ups" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"amountUnits": 0,
"reason": "Requested by guardian.",
"note": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
accountIdrequired | string (uuid) | — |
kindrequired | enum: "topup" | "debit" | "refund" | "adjustment" | — |
amountUnitsrequired | integer | -9007199254740991–9007199254740991 |
balanceAfterUnitsrequired | integer | -9007199254740991–9007199254740991 |
messageIdrequired | string (uuid) | null | — |
priceIdrequired | string (uuid) | null | — |
reasonrequired | string | null | — |
noterequired | string | null | — |
actorUserIdrequired | string (uuid) | null | — |
createdAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"kind": "topup",
"amountUnits": -9007199254740991,
"balanceAfterUnits": -9007199254740991,
"messageId": "1ac1c849-1ac1-7ac1-8c1c-1ac1c8491ac1",
"priceId": "48d77787-48d7-78d7-8d77-48d7778748d7",
"reason": "Requested by guardian.",
"note": "string",
"actorUserId": "7d892c08-7d89-7d89-8892-7d892c087d89",
"createdAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/relay/installs
List relay installs, newest first — every account, or one account with ?accountId= (K-41).
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
accountId | query | string (uuid) | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/relay/installs" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"installId": "2472867d-2472-7472-8728-2472867d2472",
"status": "approved",
"label": "string",
"baseUrl": "string",
"lastSeenAt": "2026-03-02T09:00:00.000Z",
"keyReplacedAt": "2026-03-02T09:00:00.000Z",
"updaterKeyBoundAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/relay/installs
Enrol this install with a licence-proven identity. The first install of an account is approved automatically; every further one is pending until the owner approves it.
Request body
| Name | Type | Constraints |
|---|---|---|
licenseKeyrequired | string | ≥1 chars |
installIdrequired | string | 1–200 chars |
publicKeyrequired | string | 1–4000 chars |
baseUrlrequired | string | — |
label | string | null | 0–200 chars |
Example
{
"licenseKey": "string",
"installId": "2472867d-2472-7472-8728-2472867d2472",
"publicKey": "string",
"baseUrl": "string",
"label": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/relay/installs" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"licenseKey": "string",
"installId": "2472867d-2472-7472-8728-2472867d2472",
"publicKey": "string",
"baseUrl": "string",
"label": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
accountIdrequired | string (uuid) | — |
installIdrequired | string | — |
statusrequired | enum: "approved" | "pending" | "blocked" | — |
labelrequired | string | null | — |
baseUrlrequired | string | — |
lastSeenAtrequired | string (date-time) | null | — |
keyReplacedAtrequired | string (date-time) | null | — |
updaterKeyBoundAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"installId": "2472867d-2472-7472-8728-2472867d2472",
"status": "approved",
"label": "string",
"baseUrl": "string",
"lastSeenAt": "2026-03-02T09:00:00.000Z",
"keyReplacedAt": "2026-03-02T09:00:00.000Z",
"updaterKeyBoundAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/relay/installs/{id}/approve
Approve a pending install so it may start spending. Owner only, audited.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/relay/installs/37386ae0-3738-7738-8386-37386ae03738/approve" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
accountIdrequired | string (uuid) | — |
installIdrequired | string | — |
statusrequired | enum: "approved" | "pending" | "blocked" | — |
labelrequired | string | null | — |
baseUrlrequired | string | — |
lastSeenAtrequired | string (date-time) | null | — |
keyReplacedAtrequired | string (date-time) | null | — |
updaterKeyBoundAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"installId": "2472867d-2472-7472-8728-2472867d2472",
"status": "approved",
"label": "string",
"baseUrl": "string",
"lastSeenAt": "2026-03-02T09:00:00.000Z",
"keyReplacedAt": "2026-03-02T09:00:00.000Z",
"updaterKeyBoundAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/relay/installs/{id}/block
Block an install — approved or pending — so it can never spend again. Owner only, audited.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/relay/installs/37386ae0-3738-7738-8386-37386ae03738/block" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
accountIdrequired | string (uuid) | — |
installIdrequired | string | — |
statusrequired | enum: "approved" | "pending" | "blocked" | — |
labelrequired | string | null | — |
baseUrlrequired | string | — |
lastSeenAtrequired | string (date-time) | null | — |
keyReplacedAtrequired | string (date-time) | null | — |
updaterKeyBoundAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"installId": "2472867d-2472-7472-8728-2472867d2472",
"status": "approved",
"label": "string",
"baseUrl": "string",
"lastSeenAt": "2026-03-02T09:00:00.000Z",
"keyReplacedAt": "2026-03-02T09:00:00.000Z",
"updaterKeyBoundAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/relay/installs/updater-key
Bind (or re-bind) the key this install’s updater generated, so the updater can sign fault reports while the API is down. Signed with the install’s own relay identity — never with the updater key itself.
Request body
| Name | Type | Constraints |
|---|---|---|
publicKeyrequired | string | 1–4000 chars |
Example
{
"publicKey": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/relay/installs/updater-key" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"publicKey": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
accountIdrequired | string (uuid) | — |
installIdrequired | string | — |
statusrequired | enum: "approved" | "pending" | "blocked" | — |
labelrequired | string | null | — |
baseUrlrequired | string | — |
lastSeenAtrequired | string (date-time) | null | — |
keyReplacedAtrequired | string (date-time) | null | — |
updaterKeyBoundAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"accountId": "fec33a71-fec3-7ec3-8c33-fec33a71fec3",
"installId": "2472867d-2472-7472-8728-2472867d2472",
"status": "approved",
"label": "string",
"baseUrl": "string",
"lastSeenAt": "2026-03-02T09:00:00.000Z",
"keyReplacedAt": "2026-03-02T09:00:00.000Z",
"updaterKeyBoundAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/relay/messages
This install's account's relay messages, newest first — or, with ?since=, only those updated since then (K-40, for status-mirroring polls).
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
since | query | string (date-time) | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/relay/messages" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"messageClass": "system",
"templateId": "8146aba6-8146-7146-846a-8146aba68146",
"channel": "email",
"senderMode": "platform",
"status": "accepted",
"costUnits": -9007199254740991,
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/relay/messages
Send a relay email — system (free, vendor-template only) or institute (paid, priced and debited). Idempotent on idempotencyKey.
Request body
None.
Example
"value"curl example
curl -X POST "https://your-institute.example/api/v1/platform/relay/messages" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '"value"'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
messageClassrequired | enum: "system" | "institute" | — |
templateIdrequired | string | null | — |
channelrequired | enum: "email" | "sms" | "push" | — |
senderModerequired | enum: "platform" | "institute" | — |
statusrequired | enum: "accepted" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "suppressed" | — |
costUnitsrequired | integer | -9007199254740991–9007199254740991 |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"messageClass": "system",
"templateId": "8146aba6-8146-7146-846a-8146aba68146",
"channel": "email",
"senderMode": "platform",
"status": "accepted",
"costUnits": -9007199254740991,
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/relay/messages/{id}
A single relay message this install's account owns.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/relay/messages/37386ae0-3738-7738-8386-37386ae03738" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
messageClassrequired | enum: "system" | "institute" | — |
templateIdrequired | string | null | — |
channelrequired | enum: "email" | "sms" | "push" | — |
senderModerequired | enum: "platform" | "institute" | — |
statusrequired | enum: "accepted" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "suppressed" | — |
costUnitsrequired | integer | -9007199254740991–9007199254740991 |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"messageClass": "system",
"templateId": "8146aba6-8146-7146-846a-8146aba68146",
"channel": "email",
"senderMode": "platform",
"status": "accepted",
"costUnits": -9007199254740991,
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/relay/prices
The relay price list, newest (effective-from) first.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/relay/prices" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"channel": "email",
"country": "string",
"senderMode": "platform",
"unit": "email_message",
"priceUnits": -9007199254740991,
"providerCostUnits": -9007199254740991,
"effectiveFrom": "2026-03-02T09:00:00.000Z",
"createdByUserId": "d630cadc-d630-7630-830c-d630cadcd630",
"createdAt": "2026-03-02T09:00:00.000Z"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/relay/prices
Add a new price row, effective immediately or from a future instant. Owner only — prices are never updated or deleted, so a change is always a new row.
Request body
| Name | Type | Constraints |
|---|---|---|
channelrequired | enum: "email" | "sms" | "push" | — |
countryrequired | string | 2–2 chars |
senderModerequired | enum: "platform" | "institute" | — |
unitrequired | enum: "email_message" | "sms_segment" | "push_message" | — |
priceUnitsrequired | integer | 0–9007199254740991 |
providerCostUnitsrequired | integer | 0–9007199254740991 |
effectiveFrom | string (date-time) | — |
Example
{
"channel": "email",
"country": "string",
"senderMode": "platform",
"unit": "email_message",
"priceUnits": 0,
"providerCostUnits": 0,
"effectiveFrom": "2026-03-02T09:00:00.000Z"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/relay/prices" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"channel": "email",
"country": "string",
"senderMode": "platform",
"unit": "email_message",
"priceUnits": 0,
"providerCostUnits": 0,
"effectiveFrom": "2026-03-02T09:00:00.000Z"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
channelrequired | enum: "email" | "sms" | "push" | — |
countryrequired | string | 2–2 chars |
senderModerequired | enum: "platform" | "institute" | — |
unitrequired | enum: "email_message" | "sms_segment" | "push_message" | — |
priceUnitsrequired | integer | -9007199254740991–9007199254740991 |
providerCostUnitsrequired | integer | -9007199254740991–9007199254740991 |
effectiveFromrequired | string (date-time) | — |
createdByUserIdrequired | string (uuid) | — |
createdAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"channel": "email",
"country": "string",
"senderMode": "platform",
"unit": "email_message",
"priceUnits": -9007199254740991,
"providerCostUnits": -9007199254740991,
"effectiveFrom": "2026-03-02T09:00:00.000Z",
"createdByUserId": "d630cadc-d630-7630-830c-d630cadcd630",
"createdAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/relay/webhooks/resend
Resend's bounce/complaint/delivered webhook. Svix-signature verified, idempotent.
curl example
curl -X POST "https://your-institute.example/api/v1/platform/relay/webhooks/resend" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/releases
Published releases, newest first.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
channel | query | enum: "stable" | "beta" | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/releases" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"channel": "stable",
"version": "string",
"images": {
"api": {
"ref": "string",
"digest": "string"
},
"web": {
"ref": "string",
"digest": "string"
},
"backup": {
"ref": "string",
"digest": "string"
},
"updater": {
"ref": "string",
"digest": "string"
}
},
"desiredStateSha256": "string",
"repairMode": "repair",
"minFromVersion": "string",
"notes": "Prefers afternoon sessions.",
"releasedAt": "2026-03-02T09:00:00.000Z",
"promotedAt": "2026-03-02T09:00:00.000Z"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/releases
Publish a built release (images pinned by digest). Defaults to the beta channel — promotion to stable is a separate, manual step.
Request body
| Name | Type | Constraints |
|---|---|---|
channel | enum: "stable" | "beta" | default: "beta" |
versionrequired | string | — |
imagesrequired | object | — |
desiredState | object | — |
minFromVersion | string | — |
notes | string | null | 1–5000 chars · default: null |
releasedAt | string (date-time) | — |
Example
{
"channel": "beta",
"version": "string",
"images": {
"api": {
"ref": "string",
"digest": "string"
},
"web": {
"ref": "string",
"digest": "string"
},
"backup": {
"ref": "string",
"digest": "string"
},
"updater": {
"ref": "string",
"digest": "string"
}
},
"desiredState": {
"sha256": "string",
"updaterProtocol": 1
},
"minFromVersion": "string",
"notes": null,
"releasedAt": "2026-03-02T09:00:00.000Z"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/releases" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"channel": "beta",
"version": "string",
"images": {
"api": {
"ref": "string",
"digest": "string"
},
"web": {
"ref": "string",
"digest": "string"
},
"backup": {
"ref": "string",
"digest": "string"
},
"updater": {
"ref": "string",
"digest": "string"
}
},
"desiredState": {
"sha256": "string",
"updaterProtocol": 1
},
"minFromVersion": "string",
"notes": null,
"releasedAt": "2026-03-02T09:00:00.000Z"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
channelrequired | enum: "stable" | "beta" | — |
versionrequired | string | — |
imagesrequired | object | — |
desiredStateSha256required | string | null | — |
repairModerequired | enum: "repair" | "report" | — |
minFromVersionrequired | string | — |
notesrequired | string | null | — |
releasedAtrequired | string (date-time) | — |
promotedAtrequired | string (date-time) | null | — |
warningsrequired | array<enum: "v1_only_newer_than_v2"> | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"channel": "stable",
"version": "string",
"images": {
"api": {
"ref": "string",
"digest": "string"
},
"web": {
"ref": "string",
"digest": "string"
},
"backup": {
"ref": "string",
"digest": "string"
},
"updater": {
"ref": "string",
"digest": "string"
}
},
"desiredStateSha256": "string",
"repairMode": "repair",
"minFromVersion": "string",
"notes": "Prefers afternoon sessions.",
"releasedAt": "2026-03-02T09:00:00.000Z",
"promotedAt": "2026-03-02T09:00:00.000Z",
"warnings": [
"v1_only_newer_than_v2"
]
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/releases/{releaseId}/promote
Promote a beta release to the stable channel. Platform owner only — this is what reaches every unattended install. Requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
releaseIdrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/releases/97e23b63-97e2-77e2-8e23-97e23b6397e2/promote" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
channelrequired | enum: "stable" | "beta" | — |
versionrequired | string | — |
imagesrequired | object | — |
desiredStateSha256required | string | null | — |
repairModerequired | enum: "repair" | "report" | — |
minFromVersionrequired | string | — |
notesrequired | string | null | — |
releasedAtrequired | string (date-time) | — |
promotedAtrequired | string (date-time) | null | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"channel": "stable",
"version": "string",
"images": {
"api": {
"ref": "string",
"digest": "string"
},
"web": {
"ref": "string",
"digest": "string"
},
"backup": {
"ref": "string",
"digest": "string"
},
"updater": {
"ref": "string",
"digest": "string"
}
},
"desiredStateSha256": "string",
"repairMode": "repair",
"minFromVersion": "string",
"notes": "Prefers afternoon sessions.",
"releasedAt": "2026-03-02T09:00:00.000Z",
"promotedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/releases/{releaseId}/repair-mode
Set a release's repair mode — the vendor kill switch. `report` makes every install on this release only report damage instead of repairing it. Platform owner only; refused (409) for a release without a v2 manifest. Requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
releaseIdrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
repairModerequired | enum: "repair" | "report" | — |
Example
{
"repairMode": "repair"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/releases/97e23b63-97e2-77e2-8e23-97e23b6397e2/repair-mode" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"repairMode": "repair"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
channelrequired | enum: "stable" | "beta" | — |
versionrequired | string | — |
imagesrequired | object | — |
desiredStateSha256required | string | null | — |
repairModerequired | enum: "repair" | "report" | — |
minFromVersionrequired | string | — |
notesrequired | string | null | — |
releasedAtrequired | string (date-time) | — |
promotedAtrequired | string (date-time) | null | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"channel": "stable",
"version": "string",
"images": {
"api": {
"ref": "string",
"digest": "string"
},
"web": {
"ref": "string",
"digest": "string"
},
"backup": {
"ref": "string",
"digest": "string"
},
"updater": {
"ref": "string",
"digest": "string"
}
},
"desiredStateSha256": "string",
"repairMode": "repair",
"minFromVersion": "string",
"notes": "Prefers afternoon sessions.",
"releasedAt": "2026-03-02T09:00:00.000Z",
"promotedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/releases/ci
Publish a release to the beta channel from CI, authenticated by a GitHub Actions OIDC token (no stored secret, see docs/specs/phase11-vendor-console.md §2.5).
Request body
| Name | Type | Constraints |
|---|---|---|
versionrequired | string | — |
imagesrequired | object | — |
desiredState | object | — |
minFromVersion | string | — |
notes | string | null | 1–5000 chars · default: null |
releasedAt | string (date-time) | — |
Example
{
"version": "string",
"images": {
"api": {
"ref": "string",
"digest": "string"
},
"web": {
"ref": "string",
"digest": "string"
},
"backup": {
"ref": "string",
"digest": "string"
},
"updater": {
"ref": "string",
"digest": "string"
}
},
"desiredState": {
"sha256": "string",
"updaterProtocol": 1
},
"minFromVersion": "string",
"notes": null,
"releasedAt": "2026-03-02T09:00:00.000Z"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/releases/ci" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"version": "string",
"images": {
"api": {
"ref": "string",
"digest": "string"
},
"web": {
"ref": "string",
"digest": "string"
},
"backup": {
"ref": "string",
"digest": "string"
},
"updater": {
"ref": "string",
"digest": "string"
}
},
"desiredState": {
"sha256": "string",
"updaterProtocol": 1
},
"minFromVersion": "string",
"notes": null,
"releasedAt": "2026-03-02T09:00:00.000Z"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
channelrequired | enum: "stable" | "beta" | — |
versionrequired | string | — |
imagesrequired | object | — |
desiredStateSha256required | string | null | — |
repairModerequired | enum: "repair" | "report" | — |
minFromVersionrequired | string | — |
notesrequired | string | null | — |
releasedAtrequired | string (date-time) | — |
promotedAtrequired | string (date-time) | null | — |
warningsrequired | array<enum: "v1_only_newer_than_v2"> | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"channel": "stable",
"version": "string",
"images": {
"api": {
"ref": "string",
"digest": "string"
},
"web": {
"ref": "string",
"digest": "string"
},
"backup": {
"ref": "string",
"digest": "string"
},
"updater": {
"ref": "string",
"digest": "string"
}
},
"desiredStateSha256": "string",
"repairMode": "repair",
"minFromVersion": "string",
"notes": "Prefers afternoon sessions.",
"releasedAt": "2026-03-02T09:00:00.000Z",
"promotedAt": "2026-03-02T09:00:00.000Z",
"warnings": [
"v1_only_newer_than_v2"
]
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/settings
Platform-wide settings: the global auto-lock toggle and its delay.
curl example
curl -X GET "https://your-institute.example/api/v1/platform/settings" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
autoLockEnabledrequired | boolean | — |
autoLockAfterDaysrequired | integer | 0–9007199254740991 |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"autoLockEnabled": true,
"autoLockAfterDays": 0,
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
PATCH /api/v1/platform/settings
Update the global auto-lock policy. With auto-lock off (the default) an expired tenant is never locked automatically. Requires a step-up MFA check within the last 10 minutes.
Request body
| Name | Type | Constraints |
|---|---|---|
autoLockEnabled | boolean | — |
autoLockAfterDays | integer | 0–365 |
Example
{
"autoLockEnabled": true,
"autoLockAfterDays": 0
}curl example
curl -X PATCH "https://your-institute.example/api/v1/platform/settings" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"autoLockEnabled": true,
"autoLockAfterDays": 0
}'Responses
| Name | Type | Constraints |
|---|---|---|
autoLockEnabledrequired | boolean | — |
autoLockAfterDaysrequired | integer | 0–9007199254740991 |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"autoLockEnabled": true,
"autoLockAfterDays": 0,
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/support/faults
An automatic fault report (closed schema, no free text), signed by the install’s updater sub-key or by the install. A repeat of an open fault only raises its count.
Request body
| Name | Type | Constraints |
|---|---|---|
coderequired | enum: "update_rolled_back" | "update_stuck" | "rollback_failed" | "post_update_drift" | "repair_applied" | "file_unknown_modification" | "env_missing_unrecoverable" | "repair_loop" | "backup_failed" | "backup_missing" | "backup_required_failed" | "offsite_upload_failed" | "offsite_quota_exceeded" | "disk_low" | "docker_daemon_down" | "service_unhealthy" | "registry_auth_failed" | "registry_unreachable" | "certificate_invalid" | "guardian_restored" | "guardian_tampered" | "updater_tampered" | "updater_crashloop" | "pin_unverifiable" | "manifest_bad_signature" | "digest_mismatch" | "desired_state_mismatch" | "protocol_unsupported" | "install_down" | "repair_suppressed" | "service_drift_unrecoverable" | — |
severityrequired | enum: "info" | "warning" | "critical" | — |
occurredAtrequired | string (date-time) | — |
firstSeenAtrequired | string (date-time) | — |
countrequired | integer | 1–1000000 |
versionsrequired | object | — |
steprequired | enum: "manifest" | "preflight" | "pull" | "backup" | "snapshot" | "apply" | "verify" | "commit" | "rollback" | "converge" | "guardian" | "report" | "adoption" | null | null | — |
subjectrequired | object | null | — |
errorClassrequired | enum: "timeout" | "permission_denied" | "not_found" | "auth_refused" | "network_unreachable" | "exit_nonzero" | "health_timeout" | "signature_invalid" | "digest_mismatch" | "out_of_space" | "unknown" | null | null | — |
exitCoderequired | integer | null | -255–255 |
metricsrequired | object | null | — |
backupSetIdrequired | string | null | — |
manifestSha256required | string | null | — |
Example
{
"code": "update_rolled_back",
"severity": "info",
"occurredAt": "2026-03-02T09:00:00.000Z",
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"count": 1,
"versions": {
"app": "string",
"updater": "string",
"guardian": 0
},
"step": "manifest",
"subject": {
"service": "postgres",
"path": "docker-compose.yml",
"envKey": "POSTGRES_PASSWORD"
},
"errorClass": "timeout",
"exitCode": -255,
"metrics": {
"diskFreeBytes": 0,
"diskTotalBytes": 0,
"setSizeBytes": 0,
"durationSec": 0
},
"backupSetId": "c997a5a0-c997-7997-897a-c997a5a0c997",
"manifestSha256": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/support/faults" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"code": "update_rolled_back",
"severity": "info",
"occurredAt": "2026-03-02T09:00:00.000Z",
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"count": 1,
"versions": {
"app": "string",
"updater": "string",
"guardian": 0
},
"step": "manifest",
"subject": {
"service": "postgres",
"path": "docker-compose.yml",
"envKey": "POSTGRES_PASSWORD"
},
"errorClass": "timeout",
"exitCode": -255,
"metrics": {
"diskFreeBytes": 0,
"diskTotalBytes": 0,
"setSizeBytes": 0,
"durationSec": 0
},
"backupSetId": "c997a5a0-c997-7997-897a-c997a5a0c997",
"manifestSha256": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
statusrequired | enum: "new" | "acknowledged" | "in_progress" | "resolved" | "declined" | "duplicate" | — |
createdrequired | boolean | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"status": "new",
"created": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/support/faults/unverified
The open intake for a fault when the sender could not be verified. Stored as unverified, never changes any install, at most 16 KiB, 5 per hour per address and 500 a day in all.
Request body
| Name | Type | Constraints |
|---|---|---|
coderequired | enum: "update_rolled_back" | "update_stuck" | "rollback_failed" | "post_update_drift" | "repair_applied" | "file_unknown_modification" | "env_missing_unrecoverable" | "repair_loop" | "backup_failed" | "backup_missing" | "backup_required_failed" | "offsite_upload_failed" | "offsite_quota_exceeded" | "disk_low" | "docker_daemon_down" | "service_unhealthy" | "registry_auth_failed" | "registry_unreachable" | "certificate_invalid" | "guardian_restored" | "guardian_tampered" | "updater_tampered" | "updater_crashloop" | "pin_unverifiable" | "manifest_bad_signature" | "digest_mismatch" | "desired_state_mismatch" | "protocol_unsupported" | "install_down" | "repair_suppressed" | "service_drift_unrecoverable" | — |
severityrequired | enum: "info" | "warning" | "critical" | — |
occurredAtrequired | string (date-time) | — |
firstSeenAtrequired | string (date-time) | — |
countrequired | integer | 1–1000000 |
versionsrequired | object | — |
steprequired | enum: "manifest" | "preflight" | "pull" | "backup" | "snapshot" | "apply" | "verify" | "commit" | "rollback" | "converge" | "guardian" | "report" | "adoption" | null | null | — |
subjectrequired | object | null | — |
errorClassrequired | enum: "timeout" | "permission_denied" | "not_found" | "auth_refused" | "network_unreachable" | "exit_nonzero" | "health_timeout" | "signature_invalid" | "digest_mismatch" | "out_of_space" | "unknown" | null | null | — |
exitCoderequired | integer | null | -255–255 |
metricsrequired | object | null | — |
backupSetIdrequired | string | null | — |
manifestSha256required | string | null | — |
claimedInstallIdrequired | string (uuid) | — |
Example
{
"code": "update_rolled_back",
"severity": "info",
"occurredAt": "2026-03-02T09:00:00.000Z",
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"count": 1,
"versions": {
"app": "string",
"updater": "string",
"guardian": 0
},
"step": "manifest",
"subject": {
"service": "postgres",
"path": "docker-compose.yml",
"envKey": "POSTGRES_PASSWORD"
},
"errorClass": "timeout",
"exitCode": -255,
"metrics": {
"diskFreeBytes": 0,
"diskTotalBytes": 0,
"setSizeBytes": 0,
"durationSec": 0
},
"backupSetId": "c997a5a0-c997-7997-897a-c997a5a0c997",
"manifestSha256": "string",
"claimedInstallId": "6c98b290-6c98-7c98-898b-6c98b2906c98"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/support/faults/unverified" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"code": "update_rolled_back",
"severity": "info",
"occurredAt": "2026-03-02T09:00:00.000Z",
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"count": 1,
"versions": {
"app": "string",
"updater": "string",
"guardian": 0
},
"step": "manifest",
"subject": {
"service": "postgres",
"path": "docker-compose.yml",
"envKey": "POSTGRES_PASSWORD"
},
"errorClass": "timeout",
"exitCode": -255,
"metrics": {
"diskFreeBytes": 0,
"diskTotalBytes": 0,
"setSizeBytes": 0,
"durationSec": 0
},
"backupSetId": "c997a5a0-c997-7997-897a-c997a5a0c997",
"manifestSha256": "string",
"claimedInstallId": "6c98b290-6c98-7c98-898b-6c98b2906c98"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
statusrequired | enum: "new" | "acknowledged" | "in_progress" | "resolved" | "declined" | "duplicate" | — |
createdrequired | boolean | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"status": "new",
"created": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/support/reports
List faults, problems and feature requests, newest first — filter by kind, status, verification, severity, code or customer.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
kind | query | enum: "fault" | "problem" | "feature" | — |
status | query | enum: "new" | "acknowledged" | "in_progress" | "resolved" | "declined" | "duplicate" | — |
verification | query | enum: "updater_signed" | "install_signed" | "unverified" | — |
verified | query | enum: "true" | "false" | — |
severity | query | enum: "info" | "warning" | "critical" | — |
code | query | enum: "update_rolled_back" | "update_stuck" | "rollback_failed" | "post_update_drift" | "repair_applied" | "file_unknown_modification" | "env_missing_unrecoverable" | "repair_loop" | "backup_failed" | "backup_missing" | "backup_required_failed" | "offsite_upload_failed" | "offsite_quota_exceeded" | "disk_low" | "docker_daemon_down" | "service_unhealthy" | "registry_auth_failed" | "registry_unreachable" | "certificate_invalid" | "guardian_restored" | "guardian_tampered" | "updater_tampered" | "updater_crashloop" | "pin_unverifiable" | "manifest_bad_signature" | "digest_mismatch" | "desired_state_mismatch" | "protocol_unsupported" | "install_down" | "repair_suppressed" | "service_drift_unrecoverable" | — |
tenantId | query | string (uuid) | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/support/reports" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"kind": "fault",
"source": "updater",
"verification": "updater_signed",
"status": "new",
"severity": "info",
"code": "update_rolled_back",
"category": "login_access",
"title": "Midterm Exam",
"tenant": {
"id": "37386ae0-3738-7738-8386-37386ae03738",
"name": "Algebra I",
"slug": "string"
},
"installId": "2472867d-2472-7472-8728-2472867d2472",
"claimedInstallId": "6c98b290-6c98-7c98-898b-6c98b2906c98",
"serverIp": "string",
"appVersion": "string",
"details": {
"code": "update_rolled_back",
"severity": "info",
"occurredAt": "2026-03-02T09:00:00.000Z",
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"count": 1,
"versions": {
"app": "string",
"updater": "string",
"guardian": 0
},
"step": "manifest",
"subject": {
"service": "postgres",
"path": "docker-compose.yml",
"envKey": "POSTGRES_PASSWORD"
},
"errorClass": "timeout",
"exitCode": -255,
"metrics": {
"diskFreeBytes": 0,
"diskTotalBytes": 0,
"setSizeBytes": 0,
"durationSec": 0
},
"backupSetId": "c997a5a0-c997-7997-897a-c997a5a0c997",
"manifestSha256": "string"
},
"occurrenceCount": -9007199254740991,
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"lastSeenAt": "2026-03-02T09:00:00.000Z",
"duplicateOf": "8e5c1847-8e5c-7e5c-85c1-8e5c18478e5c",
"resolvedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/support/reports/{id}
One report with its structured fields, the owner’s text and the vendor’s replies.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/support/reports/37386ae0-3738-7738-8386-37386ae03738" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
kindrequired | enum: "fault" | "problem" | "feature" | — |
sourcerequired | enum: "updater" | "guardian" | "install_ui" | "unverified_intake" | — |
verificationrequired | enum: "updater_signed" | "install_signed" | "unverified" | — |
statusrequired | enum: "new" | "acknowledged" | "in_progress" | "resolved" | "declined" | "duplicate" | — |
severityrequired | enum: "info" | "warning" | "critical" | null | null | — |
coderequired | enum: "update_rolled_back" | "update_stuck" | "rollback_failed" | "post_update_drift" | "repair_applied" | "file_unknown_modification" | "env_missing_unrecoverable" | "repair_loop" | "backup_failed" | "backup_missing" | "backup_required_failed" | "offsite_upload_failed" | "offsite_quota_exceeded" | "disk_low" | "docker_daemon_down" | "service_unhealthy" | "registry_auth_failed" | "registry_unreachable" | "certificate_invalid" | "guardian_restored" | "guardian_tampered" | "updater_tampered" | "updater_crashloop" | "pin_unverifiable" | "manifest_bad_signature" | "digest_mismatch" | "desired_state_mismatch" | "protocol_unsupported" | "install_down" | "repair_suppressed" | "service_drift_unrecoverable" | null | null | — |
categoryrequired | enum: "login_access" | "people" | "attendance" | "billing" | "courses_content" | "notifications" | "updates_backups" | "performance" | "other" | null | null | — |
titlerequired | string | null | — |
tenantrequired | object | null | — |
installIdrequired | string | null | — |
claimedInstallIdrequired | string (uuid) | null | — |
serverIprequired | string | null | — |
appVersionrequired | string | null | — |
detailsrequired | object | null | — |
occurrenceCountrequired | integer | -9007199254740991–9007199254740991 |
firstSeenAtrequired | string (date-time) | — |
lastSeenAtrequired | string (date-time) | — |
duplicateOfrequired | string (uuid) | null | — |
resolvedAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
bodyrequired | string | null | — |
messagesrequired | array<object> | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"kind": "fault",
"source": "updater",
"verification": "updater_signed",
"status": "new",
"severity": "info",
"code": "update_rolled_back",
"category": "login_access",
"title": "Midterm Exam",
"tenant": {
"id": "37386ae0-3738-7738-8386-37386ae03738",
"name": "Algebra I",
"slug": "string"
},
"installId": "2472867d-2472-7472-8728-2472867d2472",
"claimedInstallId": "6c98b290-6c98-7c98-898b-6c98b2906c98",
"serverIp": "string",
"appVersion": "string",
"details": {
"code": "update_rolled_back",
"severity": "info",
"occurredAt": "2026-03-02T09:00:00.000Z",
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"count": 1,
"versions": {
"app": "string",
"updater": "string",
"guardian": 0
},
"step": "manifest",
"subject": {
"service": "postgres",
"path": "docker-compose.yml",
"envKey": "POSTGRES_PASSWORD"
},
"errorClass": "timeout",
"exitCode": -255,
"metrics": {
"diskFreeBytes": 0,
"diskTotalBytes": 0,
"setSizeBytes": 0,
"durationSec": 0
},
"backupSetId": "c997a5a0-c997-7997-897a-c997a5a0c997",
"manifestSha256": "string"
},
"occurrenceCount": -9007199254740991,
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"lastSeenAt": "2026-03-02T09:00:00.000Z",
"duplicateOf": "8e5c1847-8e5c-7e5c-85c1-8e5c18478e5c",
"resolvedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z",
"body": "string",
"messages": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"author": "vendor",
"body": "string",
"createdAt": "2026-03-02T09:00:00.000Z"
}
]
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/support/reports/{id}/duplicate
Mark a report as a duplicate of an earlier one of the same kind. Audited.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
duplicateOfrequired | string (uuid) | — |
Example
{
"duplicateOf": "8e5c1847-8e5c-7e5c-85c1-8e5c18478e5c"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/support/reports/37386ae0-3738-7738-8386-37386ae03738/duplicate" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"duplicateOf": "8e5c1847-8e5c-7e5c-85c1-8e5c18478e5c"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
kindrequired | enum: "fault" | "problem" | "feature" | — |
sourcerequired | enum: "updater" | "guardian" | "install_ui" | "unverified_intake" | — |
verificationrequired | enum: "updater_signed" | "install_signed" | "unverified" | — |
statusrequired | enum: "new" | "acknowledged" | "in_progress" | "resolved" | "declined" | "duplicate" | — |
severityrequired | enum: "info" | "warning" | "critical" | null | null | — |
coderequired | enum: "update_rolled_back" | "update_stuck" | "rollback_failed" | "post_update_drift" | "repair_applied" | "file_unknown_modification" | "env_missing_unrecoverable" | "repair_loop" | "backup_failed" | "backup_missing" | "backup_required_failed" | "offsite_upload_failed" | "offsite_quota_exceeded" | "disk_low" | "docker_daemon_down" | "service_unhealthy" | "registry_auth_failed" | "registry_unreachable" | "certificate_invalid" | "guardian_restored" | "guardian_tampered" | "updater_tampered" | "updater_crashloop" | "pin_unverifiable" | "manifest_bad_signature" | "digest_mismatch" | "desired_state_mismatch" | "protocol_unsupported" | "install_down" | "repair_suppressed" | "service_drift_unrecoverable" | null | null | — |
categoryrequired | enum: "login_access" | "people" | "attendance" | "billing" | "courses_content" | "notifications" | "updates_backups" | "performance" | "other" | null | null | — |
titlerequired | string | null | — |
tenantrequired | object | null | — |
installIdrequired | string | null | — |
claimedInstallIdrequired | string (uuid) | null | — |
serverIprequired | string | null | — |
appVersionrequired | string | null | — |
detailsrequired | object | null | — |
occurrenceCountrequired | integer | -9007199254740991–9007199254740991 |
firstSeenAtrequired | string (date-time) | — |
lastSeenAtrequired | string (date-time) | — |
duplicateOfrequired | string (uuid) | null | — |
resolvedAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"kind": "fault",
"source": "updater",
"verification": "updater_signed",
"status": "new",
"severity": "info",
"code": "update_rolled_back",
"category": "login_access",
"title": "Midterm Exam",
"tenant": {
"id": "37386ae0-3738-7738-8386-37386ae03738",
"name": "Algebra I",
"slug": "string"
},
"installId": "2472867d-2472-7472-8728-2472867d2472",
"claimedInstallId": "6c98b290-6c98-7c98-898b-6c98b2906c98",
"serverIp": "string",
"appVersion": "string",
"details": {
"code": "update_rolled_back",
"severity": "info",
"occurredAt": "2026-03-02T09:00:00.000Z",
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"count": 1,
"versions": {
"app": "string",
"updater": "string",
"guardian": 0
},
"step": "manifest",
"subject": {
"service": "postgres",
"path": "docker-compose.yml",
"envKey": "POSTGRES_PASSWORD"
},
"errorClass": "timeout",
"exitCode": -255,
"metrics": {
"diskFreeBytes": 0,
"diskTotalBytes": 0,
"setSizeBytes": 0,
"durationSec": 0
},
"backupSetId": "c997a5a0-c997-7997-897a-c997a5a0c997",
"manifestSha256": "string"
},
"occurrenceCount": -9007199254740991,
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"lastSeenAt": "2026-03-02T09:00:00.000Z",
"duplicateOf": "8e5c1847-8e5c-7e5c-85c1-8e5c18478e5c",
"resolvedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/support/reports/{id}/reply
Reply to a problem or a feature request; the institute’s owner sees the reply on their install. Audited.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
bodyrequired | string | 1–4000 chars |
Example
{
"body": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/support/reports/37386ae0-3738-7738-8386-37386ae03738/reply" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"body": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
kindrequired | enum: "fault" | "problem" | "feature" | — |
sourcerequired | enum: "updater" | "guardian" | "install_ui" | "unverified_intake" | — |
verificationrequired | enum: "updater_signed" | "install_signed" | "unverified" | — |
statusrequired | enum: "new" | "acknowledged" | "in_progress" | "resolved" | "declined" | "duplicate" | — |
severityrequired | enum: "info" | "warning" | "critical" | null | null | — |
coderequired | enum: "update_rolled_back" | "update_stuck" | "rollback_failed" | "post_update_drift" | "repair_applied" | "file_unknown_modification" | "env_missing_unrecoverable" | "repair_loop" | "backup_failed" | "backup_missing" | "backup_required_failed" | "offsite_upload_failed" | "offsite_quota_exceeded" | "disk_low" | "docker_daemon_down" | "service_unhealthy" | "registry_auth_failed" | "registry_unreachable" | "certificate_invalid" | "guardian_restored" | "guardian_tampered" | "updater_tampered" | "updater_crashloop" | "pin_unverifiable" | "manifest_bad_signature" | "digest_mismatch" | "desired_state_mismatch" | "protocol_unsupported" | "install_down" | "repair_suppressed" | "service_drift_unrecoverable" | null | null | — |
categoryrequired | enum: "login_access" | "people" | "attendance" | "billing" | "courses_content" | "notifications" | "updates_backups" | "performance" | "other" | null | null | — |
titlerequired | string | null | — |
tenantrequired | object | null | — |
installIdrequired | string | null | — |
claimedInstallIdrequired | string (uuid) | null | — |
serverIprequired | string | null | — |
appVersionrequired | string | null | — |
detailsrequired | object | null | — |
occurrenceCountrequired | integer | -9007199254740991–9007199254740991 |
firstSeenAtrequired | string (date-time) | — |
lastSeenAtrequired | string (date-time) | — |
duplicateOfrequired | string (uuid) | null | — |
resolvedAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
bodyrequired | string | null | — |
messagesrequired | array<object> | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"kind": "fault",
"source": "updater",
"verification": "updater_signed",
"status": "new",
"severity": "info",
"code": "update_rolled_back",
"category": "login_access",
"title": "Midterm Exam",
"tenant": {
"id": "37386ae0-3738-7738-8386-37386ae03738",
"name": "Algebra I",
"slug": "string"
},
"installId": "2472867d-2472-7472-8728-2472867d2472",
"claimedInstallId": "6c98b290-6c98-7c98-898b-6c98b2906c98",
"serverIp": "string",
"appVersion": "string",
"details": {
"code": "update_rolled_back",
"severity": "info",
"occurredAt": "2026-03-02T09:00:00.000Z",
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"count": 1,
"versions": {
"app": "string",
"updater": "string",
"guardian": 0
},
"step": "manifest",
"subject": {
"service": "postgres",
"path": "docker-compose.yml",
"envKey": "POSTGRES_PASSWORD"
},
"errorClass": "timeout",
"exitCode": -255,
"metrics": {
"diskFreeBytes": 0,
"diskTotalBytes": 0,
"setSizeBytes": 0,
"durationSec": 0
},
"backupSetId": "c997a5a0-c997-7997-897a-c997a5a0c997",
"manifestSha256": "string"
},
"occurrenceCount": -9007199254740991,
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"lastSeenAt": "2026-03-02T09:00:00.000Z",
"duplicateOf": "8e5c1847-8e5c-7e5c-85c1-8e5c18478e5c",
"resolvedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z",
"body": "string",
"messages": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"author": "vendor",
"body": "string",
"createdAt": "2026-03-02T09:00:00.000Z"
}
]
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/support/reports/{id}/status
Acknowledge, start, resolve or decline a report. Audited.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
statusrequired | enum: "new" | "acknowledged" | "in_progress" | "resolved" | "declined" | "duplicate" | — |
Example
{
"status": "new"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/support/reports/37386ae0-3738-7738-8386-37386ae03738/status" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"status": "new"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
kindrequired | enum: "fault" | "problem" | "feature" | — |
sourcerequired | enum: "updater" | "guardian" | "install_ui" | "unverified_intake" | — |
verificationrequired | enum: "updater_signed" | "install_signed" | "unverified" | — |
statusrequired | enum: "new" | "acknowledged" | "in_progress" | "resolved" | "declined" | "duplicate" | — |
severityrequired | enum: "info" | "warning" | "critical" | null | null | — |
coderequired | enum: "update_rolled_back" | "update_stuck" | "rollback_failed" | "post_update_drift" | "repair_applied" | "file_unknown_modification" | "env_missing_unrecoverable" | "repair_loop" | "backup_failed" | "backup_missing" | "backup_required_failed" | "offsite_upload_failed" | "offsite_quota_exceeded" | "disk_low" | "docker_daemon_down" | "service_unhealthy" | "registry_auth_failed" | "registry_unreachable" | "certificate_invalid" | "guardian_restored" | "guardian_tampered" | "updater_tampered" | "updater_crashloop" | "pin_unverifiable" | "manifest_bad_signature" | "digest_mismatch" | "desired_state_mismatch" | "protocol_unsupported" | "install_down" | "repair_suppressed" | "service_drift_unrecoverable" | null | null | — |
categoryrequired | enum: "login_access" | "people" | "attendance" | "billing" | "courses_content" | "notifications" | "updates_backups" | "performance" | "other" | null | null | — |
titlerequired | string | null | — |
tenantrequired | object | null | — |
installIdrequired | string | null | — |
claimedInstallIdrequired | string (uuid) | null | — |
serverIprequired | string | null | — |
appVersionrequired | string | null | — |
detailsrequired | object | null | — |
occurrenceCountrequired | integer | -9007199254740991–9007199254740991 |
firstSeenAtrequired | string (date-time) | — |
lastSeenAtrequired | string (date-time) | — |
duplicateOfrequired | string (uuid) | null | — |
resolvedAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"kind": "fault",
"source": "updater",
"verification": "updater_signed",
"status": "new",
"severity": "info",
"code": "update_rolled_back",
"category": "login_access",
"title": "Midterm Exam",
"tenant": {
"id": "37386ae0-3738-7738-8386-37386ae03738",
"name": "Algebra I",
"slug": "string"
},
"installId": "2472867d-2472-7472-8728-2472867d2472",
"claimedInstallId": "6c98b290-6c98-7c98-898b-6c98b2906c98",
"serverIp": "string",
"appVersion": "string",
"details": {
"code": "update_rolled_back",
"severity": "info",
"occurredAt": "2026-03-02T09:00:00.000Z",
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"count": 1,
"versions": {
"app": "string",
"updater": "string",
"guardian": 0
},
"step": "manifest",
"subject": {
"service": "postgres",
"path": "docker-compose.yml",
"envKey": "POSTGRES_PASSWORD"
},
"errorClass": "timeout",
"exitCode": -255,
"metrics": {
"diskFreeBytes": 0,
"diskTotalBytes": 0,
"setSizeBytes": 0,
"durationSec": 0
},
"backupSetId": "c997a5a0-c997-7997-897a-c997a5a0c997",
"manifestSha256": "string"
},
"occurrenceCount": -9007199254740991,
"firstSeenAt": "2026-03-02T09:00:00.000Z",
"lastSeenAt": "2026-03-02T09:00:00.000Z",
"duplicateOf": "8e5c1847-8e5c-7e5c-85c1-8e5c18478e5c",
"resolvedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/support/reports/summary
What is new, split the way the console tabs are — the numbers behind the sidebar badge.
curl example
curl -X GET "https://your-institute.example/api/v1/platform/support/reports/summary" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
newCriticalFaultsrequired | integer | -9007199254740991–9007199254740991 |
newFaultsrequired | integer | -9007199254740991–9007199254740991 |
newProblemsrequired | integer | -9007199254740991–9007199254740991 |
newFeaturesrequired | integer | -9007199254740991–9007199254740991 |
newUnverifiedrequired | integer | -9007199254740991–9007199254740991 |
{
"newCriticalFaults": -9007199254740991,
"newFaults": -9007199254740991,
"newProblems": -9007199254740991,
"newFeatures": -9007199254740991,
"newUnverified": -9007199254740991
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/support/requests
This install’s customer’s own problem and feature requests with their status and the vendor’s replies, newest first; ?since= narrows to what changed. Never another customer’s.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
since | query | string (date-time) | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/support/requests" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"clientRef": "97cc9cef-97cc-77cc-8cc9-97cc9cef97cc",
"kind": "problem",
"category": "login_access",
"title": "Midterm Exam",
"status": "new",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z",
"replies": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"body": "string",
"createdAt": "2026-03-02T09:00:00.000Z"
}
]
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/support/requests
A problem report or a feature request an institute’s owner wrote, signed by the install. Idempotent on clientRef; carries no author name or email.
Request body
| Name | Type | Constraints |
|---|---|---|
clientRefrequired | string (uuid) | — |
kindrequired | enum: "problem" | "feature" | — |
categoryrequired | enum: "login_access" | "people" | "attendance" | "billing" | "courses_content" | "notifications" | "updates_backups" | "performance" | "other" | — |
titlerequired | string | 1–120 chars |
textrequired | string | 1–4000 chars |
Example
{
"clientRef": "97cc9cef-97cc-77cc-8cc9-97cc9cef97cc",
"kind": "problem",
"category": "login_access",
"title": "Midterm Exam",
"text": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/support/requests" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"clientRef": "97cc9cef-97cc-77cc-8cc9-97cc9cef97cc",
"kind": "problem",
"category": "login_access",
"title": "Midterm Exam",
"text": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
statusrequired | enum: "new" | "acknowledged" | "in_progress" | "resolved" | "declined" | "duplicate" | — |
createdrequired | boolean | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"status": "new",
"created": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/tenants
List tenants (cursor-paginated, optional name search and status filter).
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
search | query | string | 1–200 chars |
status | query | enum: "active" | "suspended" | "archived" | "deleted" | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/tenants" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"slug": "string",
"name": "Algebra I",
"status": "active",
"defaultLocale": "ar",
"timezone": "string",
"currency": "USD",
"deploymentMode": "cloud",
"autoLockOverride": "inherit",
"lockedAt": "2026-03-02T09:00:00.000Z",
"lockedReason": "string",
"lockedByPlatformAdminId": "f0abde01-f0ab-70ab-8abd-f0abde01f0ab",
"createdBy": "0b14e5a6-0b14-7b14-814e-0b14e5a60b14",
"deletedAt": "2026-03-02T09:00:00.000Z",
"deletedName": "string",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z",
"subscriptionStatus": "trialing"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants
Create a tenant: seeds its default branch/roles, primary subdomain, trial subscription, and emails the owner an invitation.
Request body
| Name | Type | Constraints |
|---|---|---|
slugrequired | string | 3–40 chars |
namerequired | string | 1–200 chars |
defaultLocalerequired | enum: "ar" | "en" | "he" | — |
timezone | string | 1–100 chars |
currency | string | 3–3 chars |
deploymentMode | enum: "cloud" | "self_hosted" | — |
planrequired | string | 1–50 chars |
trialDaysrequired | integer | 0–365 |
ownerEmailrequired | string (email) | — |
Example
{
"slug": "string",
"name": "Algebra I",
"defaultLocale": "ar",
"timezone": "string",
"currency": "USD",
"deploymentMode": "cloud",
"plan": "string",
"trialDays": 0,
"ownerEmail": "ada.lovelace@example.com"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"slug": "string",
"name": "Algebra I",
"defaultLocale": "ar",
"timezone": "string",
"currency": "USD",
"deploymentMode": "cloud",
"plan": "string",
"trialDays": 0,
"ownerEmail": "ada.lovelace@example.com"
}'Responses
| Name | Type | Constraints |
|---|---|---|
tenantrequired | object | — |
domainrequired | string | — |
invitationIdrequired | string (uuid) | — |
portalOwnerrequired | unknown | — |
{
"tenant": {
"id": "37386ae0-3738-7738-8386-37386ae03738",
"slug": "string",
"name": "Algebra I",
"status": "active",
"defaultLocale": "ar",
"timezone": "string",
"currency": "USD",
"deploymentMode": "cloud",
"autoLockOverride": "inherit",
"lockedAt": "2026-03-02T09:00:00.000Z",
"lockedReason": "string",
"lockedByPlatformAdminId": "f0abde01-f0ab-70ab-8abd-f0abde01f0ab",
"createdBy": "0b14e5a6-0b14-7b14-814e-0b14e5a60b14",
"deletedAt": "2026-03-02T09:00:00.000Z",
"deletedName": "string",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
},
"domain": "string",
"invitationId": "00637243-0063-7063-8637-006372430063",
"portalOwner": "value"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/tenants/{id}
Tenant detail: subscription, domains, member/branch counts.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/tenants/37386ae0-3738-7738-8386-37386ae03738" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
tenantrequired | object | — |
subscriptionrequired | object | null | — |
domainsrequired | array<object> | — |
countsrequired | object | — |
endedAtrequired | string (date-time) | null | — |
portalOwnerrequired | unknown | — |
{
"tenant": {
"id": "37386ae0-3738-7738-8386-37386ae03738",
"slug": "string",
"name": "Algebra I",
"status": "active",
"defaultLocale": "ar",
"timezone": "string",
"currency": "USD",
"deploymentMode": "cloud",
"autoLockOverride": "inherit",
"lockedAt": "2026-03-02T09:00:00.000Z",
"lockedReason": "string",
"lockedByPlatformAdminId": "f0abde01-f0ab-70ab-8abd-f0abde01f0ab",
"createdBy": "0b14e5a6-0b14-7b14-814e-0b14e5a60b14",
"deletedAt": "2026-03-02T09:00:00.000Z",
"deletedName": "string",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
},
"subscription": {
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"planId": "744bf63f-744b-744b-84bf-744bf63f744b",
"status": "trialing",
"currentPeriodStart": "2026-03-02T09:00:00.000Z",
"currentPeriodEnd": "2026-03-02T09:00:00.000Z",
"cancelledAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
},
"domains": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"domain": "string",
"kind": "subdomain",
"verificationToken": "string",
"verifiedAt": "2026-03-02T09:00:00.000Z",
"isPrimary": true,
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}
],
"counts": {
"members": -9007199254740991,
"branches": -9007199254740991
},
"endedAt": "2026-03-02T09:00:00.000Z",
"portalOwner": "value"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
PATCH /api/v1/platform/tenants/{id}
Update a tenant’s name, locale, timezone, currency, or per-tenant auto-lock override. Changing the auto-lock override is owner only.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
name | string | 1–200 chars |
defaultLocale | enum: "ar" | "en" | "he" | — |
timezone | string | 1–100 chars |
currency | string | 3–3 chars |
autoLockOverride | enum: "inherit" | "on" | "off" | — |
Example
{
"name": "Algebra I",
"defaultLocale": "ar",
"timezone": "string",
"currency": "USD",
"autoLockOverride": "inherit"
}curl example
curl -X PATCH "https://your-institute.example/api/v1/platform/tenants/37386ae0-3738-7738-8386-37386ae03738" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Algebra I",
"defaultLocale": "ar",
"timezone": "string",
"currency": "USD",
"autoLockOverride": "inherit"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
slugrequired | string | — |
namerequired | string | — |
statusrequired | enum: "active" | "suspended" | "archived" | "deleted" | — |
defaultLocalerequired | enum: "ar" | "en" | "he" | — |
timezonerequired | string | — |
currencyrequired | string | 3–3 chars |
deploymentModerequired | enum: "cloud" | "self_hosted" | — |
autoLockOverriderequired | enum: "inherit" | "on" | "off" | — |
lockedAtrequired | string (date-time) | null | — |
lockedReasonrequired | string | null | — |
lockedByPlatformAdminIdrequired | string (uuid) | null | — |
createdByrequired | string (uuid) | null | — |
deletedAtrequired | string (date-time) | null | — |
deletedNamerequired | string | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"slug": "string",
"name": "Algebra I",
"status": "active",
"defaultLocale": "ar",
"timezone": "string",
"currency": "USD",
"deploymentMode": "cloud",
"autoLockOverride": "inherit",
"lockedAt": "2026-03-02T09:00:00.000Z",
"lockedReason": "string",
"lockedByPlatformAdminId": "f0abde01-f0ab-70ab-8abd-f0abde01f0ab",
"createdBy": "0b14e5a6-0b14-7b14-814e-0b14e5a60b14",
"deletedAt": "2026-03-02T09:00:00.000Z",
"deletedName": "string",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{id}/delete
Delete an ended (archived) customer’s data: every row of the tenant in every tenant-scoped table, its files in object storage, its domains, and the users who belong to no other tenant. Kept: audit log, licences, subscriptions, install tokens, registry credentials, relay account and ledger, customer requests — and the tenant row as a tombstone (status `deleted`, slug renamed free). `confirmName` must equal the tenant’s name exactly. 409 unless the tenant is archived. Owner only; requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
confirmNamerequired | string | 1–200 chars |
Example
{
"confirmName": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/37386ae0-3738-7738-8386-37386ae03738/delete" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"confirmName": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
tenantrequired | object | — |
deletedRowsrequired | integer | 0–9007199254740991 |
deletedUsersrequired | integer | 0–9007199254740991 |
storageCleanuprequired | enum: "done" | "failed" | — |
{
"tenant": {
"id": "37386ae0-3738-7738-8386-37386ae03738",
"slug": "string",
"name": "Algebra I",
"status": "active",
"defaultLocale": "ar",
"timezone": "string",
"currency": "USD",
"deploymentMode": "cloud",
"autoLockOverride": "inherit",
"lockedAt": "2026-03-02T09:00:00.000Z",
"lockedReason": "string",
"lockedByPlatformAdminId": "f0abde01-f0ab-70ab-8abd-f0abde01f0ab",
"createdBy": "0b14e5a6-0b14-7b14-814e-0b14e5a60b14",
"deletedAt": "2026-03-02T09:00:00.000Z",
"deletedName": "string",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
},
"deletedRows": 0,
"deletedUsers": 0,
"storageCleanup": "done"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{id}/end
End a customer: revokes every licence and registry credential, closes the relay account, and archives the tenant. Nothing is deleted. Owner only; requires a step-up MFA check within the last 10 minutes; idempotent.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/37386ae0-3738-7738-8386-37386ae03738/end" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
slugrequired | string | — |
namerequired | string | — |
statusrequired | enum: "active" | "suspended" | "archived" | "deleted" | — |
defaultLocalerequired | enum: "ar" | "en" | "he" | — |
timezonerequired | string | — |
currencyrequired | string | 3–3 chars |
deploymentModerequired | enum: "cloud" | "self_hosted" | — |
autoLockOverriderequired | enum: "inherit" | "on" | "off" | — |
lockedAtrequired | string (date-time) | null | — |
lockedReasonrequired | string | null | — |
lockedByPlatformAdminIdrequired | string (uuid) | null | — |
createdByrequired | string (uuid) | null | — |
deletedAtrequired | string (date-time) | null | — |
deletedNamerequired | string | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"slug": "string",
"name": "Algebra I",
"status": "active",
"defaultLocale": "ar",
"timezone": "string",
"currency": "USD",
"deploymentMode": "cloud",
"autoLockOverride": "inherit",
"lockedAt": "2026-03-02T09:00:00.000Z",
"lockedReason": "string",
"lockedByPlatformAdminId": "f0abde01-f0ab-70ab-8abd-f0abde01f0ab",
"createdBy": "0b14e5a6-0b14-7b14-814e-0b14e5a60b14",
"deletedAt": "2026-03-02T09:00:00.000Z",
"deletedName": "string",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{id}/impersonate
Issue a 10-minute access token for the tenant’s owner membership (audited). Owner only; requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
reasonrequired | string | 1–500 chars |
Example
{
"reason": "Requested by guardian."
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/37386ae0-3738-7738-8386-37386ae03738/impersonate" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"reason": "Requested by guardian."
}'Responses
| Name | Type | Constraints |
|---|---|---|
accessTokenrequired | string | — |
expiresInSecrequired | integer | -9007199254740991–9007199254740991 |
{
"accessToken": "string",
"expiresInSec": -9007199254740991
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{id}/link-portal-owner
Link or invite a portal owner for an institute that has none (docs/specs/phase17-unified-login.md §5.3, closes K-68). Owner only; requires a step-up MFA check within the last 10 minutes; refuses if the institute already has a portal owner, or if the email already owns a different institute.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
emailrequired | string (email) | — |
Example
{
"email": "ada.lovelace@example.com"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/37386ae0-3738-7738-8386-37386ae03738/link-portal-owner" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"email": "ada.lovelace@example.com"
}'Responses
"value"Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{id}/lock
Lock a tenant explicitly: its subscription becomes suspended and every member request gets 402 (except the allowlist). Expiry alone never does this.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
reasonrequired | string | 1–500 chars |
Example
{
"reason": "Requested by guardian."
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/37386ae0-3738-7738-8386-37386ae03738/lock" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"reason": "Requested by guardian."
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
planIdrequired | string (uuid) | — |
statusrequired | enum: "trialing" | "active" | "expired" | "suspended" | "cancelled" | — |
currentPeriodStartrequired | string (date-time) | — |
currentPeriodEndrequired | string (date-time) | — |
cancelledAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"planId": "744bf63f-744b-744b-84bf-744bf63f744b",
"status": "trialing",
"currentPeriodStart": "2026-03-02T09:00:00.000Z",
"currentPeriodEnd": "2026-03-02T09:00:00.000Z",
"cancelledAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{id}/reactivate
Reactivate a suspended tenant. Owner only.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/37386ae0-3738-7738-8386-37386ae03738/reactivate" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
slugrequired | string | — |
namerequired | string | — |
statusrequired | enum: "active" | "suspended" | "archived" | "deleted" | — |
defaultLocalerequired | enum: "ar" | "en" | "he" | — |
timezonerequired | string | — |
currencyrequired | string | 3–3 chars |
deploymentModerequired | enum: "cloud" | "self_hosted" | — |
autoLockOverriderequired | enum: "inherit" | "on" | "off" | — |
lockedAtrequired | string (date-time) | null | — |
lockedReasonrequired | string | null | — |
lockedByPlatformAdminIdrequired | string (uuid) | null | — |
createdByrequired | string (uuid) | null | — |
deletedAtrequired | string (date-time) | null | — |
deletedNamerequired | string | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"slug": "string",
"name": "Algebra I",
"status": "active",
"defaultLocale": "ar",
"timezone": "string",
"currency": "USD",
"deploymentMode": "cloud",
"autoLockOverride": "inherit",
"lockedAt": "2026-03-02T09:00:00.000Z",
"lockedReason": "string",
"lockedByPlatformAdminId": "f0abde01-f0ab-70ab-8abd-f0abde01f0ab",
"createdBy": "0b14e5a6-0b14-7b14-814e-0b14e5a60b14",
"deletedAt": "2026-03-02T09:00:00.000Z",
"deletedName": "string",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{id}/suspend
Suspend a tenant. Every member request then gets 402 (except the allowlist). Owner only.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/37386ae0-3738-7738-8386-37386ae03738/suspend" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
slugrequired | string | — |
namerequired | string | — |
statusrequired | enum: "active" | "suspended" | "archived" | "deleted" | — |
defaultLocalerequired | enum: "ar" | "en" | "he" | — |
timezonerequired | string | — |
currencyrequired | string | 3–3 chars |
deploymentModerequired | enum: "cloud" | "self_hosted" | — |
autoLockOverriderequired | enum: "inherit" | "on" | "off" | — |
lockedAtrequired | string (date-time) | null | — |
lockedReasonrequired | string | null | — |
lockedByPlatformAdminIdrequired | string (uuid) | null | — |
createdByrequired | string (uuid) | null | — |
deletedAtrequired | string (date-time) | null | — |
deletedNamerequired | string | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"slug": "string",
"name": "Algebra I",
"status": "active",
"defaultLocale": "ar",
"timezone": "string",
"currency": "USD",
"deploymentMode": "cloud",
"autoLockOverride": "inherit",
"lockedAt": "2026-03-02T09:00:00.000Z",
"lockedReason": "string",
"lockedByPlatformAdminId": "f0abde01-f0ab-70ab-8abd-f0abde01f0ab",
"createdBy": "0b14e5a6-0b14-7b14-814e-0b14e5a60b14",
"deletedAt": "2026-03-02T09:00:00.000Z",
"deletedName": "string",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{id}/unarchive
Restore an ended (archived) customer: the tenant becomes active and its members can sign in again; a relay account that "end" closed is reopened. Licences, registry credentials and install commands stay revoked — re-issue them from the Customer tab (`reissueRequired`). 409 unless the tenant is archived. Owner only; requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/37386ae0-3738-7738-8386-37386ae03738/unarchive" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
tenantrequired | object | — |
relayAccountrequired | enum: "reopened" | "unchanged" | "none" | — |
reissueRequiredrequired | array<enum: "licenses" | "registry_credentials" | "install_command"> | — |
{
"tenant": {
"id": "37386ae0-3738-7738-8386-37386ae03738",
"slug": "string",
"name": "Algebra I",
"status": "active",
"defaultLocale": "ar",
"timezone": "string",
"currency": "USD",
"deploymentMode": "cloud",
"autoLockOverride": "inherit",
"lockedAt": "2026-03-02T09:00:00.000Z",
"lockedReason": "string",
"lockedByPlatformAdminId": "f0abde01-f0ab-70ab-8abd-f0abde01f0ab",
"createdBy": "0b14e5a6-0b14-7b14-814e-0b14e5a60b14",
"deletedAt": "2026-03-02T09:00:00.000Z",
"deletedName": "string",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
},
"relayAccount": "reopened",
"reissueRequired": [
"licenses"
]
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{id}/unlock
Unlock a tenant: back to active, or expired if the paid period has run out.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/37386ae0-3738-7738-8386-37386ae03738/unlock" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
planIdrequired | string (uuid) | — |
statusrequired | enum: "trialing" | "active" | "expired" | "suspended" | "cancelled" | — |
currentPeriodStartrequired | string (date-time) | — |
currentPeriodEndrequired | string (date-time) | — |
cancelledAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"planId": "744bf63f-744b-744b-84bf-744bf63f744b",
"status": "trialing",
"currentPeriodStart": "2026-03-02T09:00:00.000Z",
"currentPeriodEnd": "2026-03-02T09:00:00.000Z",
"cancelledAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/tenants/{tenantId}/bundle
Download the customer install bundle (docker-compose.yml, .env.example, Caddyfile, README-FIRST.md) as a tar.gz for a published version.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
versionrequired | query | string | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/bundle?version=string" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
The API's OpenAPI spec doesn't declare a typed schema for this response yet — it's still JSON, just not documented here.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{tenantId}/domains
Add a custom domain (CNAME). Returns a verification token to publish as a DNS TXT record.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
domainrequired | string | 3–253 chars |
Example
{
"domain": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/domains" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"domain": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
domainrequired | string | — |
kindrequired | enum: "subdomain" | "custom" | — |
verificationTokenrequired | string | — |
verifiedAtrequired | string (date-time) | null | — |
isPrimaryrequired | boolean | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"domain": "string",
"kind": "subdomain",
"verificationToken": "string",
"verifiedAt": "2026-03-02T09:00:00.000Z",
"isPrimary": true,
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
DELETE /api/v1/platform/tenants/{tenantId}/domains/{domainId}
Remove a custom domain (the primary domain cannot be removed).
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
domainIdrequired | path | string | — |
curl example
curl -X DELETE "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/domains/f5472324-f547-7547-8472-f5472324f547" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{tenantId}/domains/{domainId}/verify
Verify a custom domain by DNS TXT lookup at `_ims-verify.<domain>`.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
domainIdrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/domains/f5472324-f547-7547-8472-f5472324f547/verify" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
domainrequired | string | — |
kindrequired | enum: "subdomain" | "custom" | — |
verificationTokenrequired | string | — |
verifiedAtrequired | string (date-time) | null | — |
isPrimaryrequired | boolean | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"domain": "string",
"kind": "subdomain",
"verificationToken": "string",
"verifiedAt": "2026-03-02T09:00:00.000Z",
"isPrimary": true,
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/tenants/{tenantId}/install-tokens
List this tenant's install tokens (state derived: unused / used / expired / revoked).
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/install-tokens" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
[
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"state": "unused",
"expiresAt": "2026-03-02T09:00:00.000Z",
"usedAt": "2026-03-02T09:00:00.000Z",
"usedFromIp": "string",
"revokedAt": "2026-03-02T09:00:00.000Z",
"createdBy": "0b14e5a6-0b14-7b14-814e-0b14e5a60b14",
"createdByAccountId": "34bcf5dc-34bc-74bc-8bcf-34bcf5dc34bc",
"label": "string",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}
]Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{tenantId}/install-tokens
Generate a one-time install command for this tenant. The raw token is returned exactly once. Owner only.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
label | string | 1–200 chars |
Example
{
"label": "string"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/install-tokens" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"label": "string"
}'Responses
| Name | Type | Constraints |
|---|---|---|
tokenrequired | object | — |
rawTokenrequired | string | — |
commandrequired | string | — |
{
"token": {
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"state": "unused",
"expiresAt": "2026-03-02T09:00:00.000Z",
"usedAt": "2026-03-02T09:00:00.000Z",
"usedFromIp": "string",
"revokedAt": "2026-03-02T09:00:00.000Z",
"createdBy": "0b14e5a6-0b14-7b14-814e-0b14e5a60b14",
"createdByAccountId": "34bcf5dc-34bc-74bc-8bcf-34bcf5dc34bc",
"label": "string",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
},
"rawToken": "string",
"command": "string"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
DELETE /api/v1/platform/tenants/{tenantId}/install-tokens/{tokenId}
Revoke an unused install token. A used or already-revoked token cannot be revoked again.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
tokenIdrequired | path | string | — |
curl example
curl -X DELETE "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/install-tokens/3ab6031f-3ab6-7ab6-8b60-3ab6031f3ab6" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
staterequired | enum: "unused" | "used" | "expired" | "revoked" | — |
expiresAtrequired | string (date-time) | — |
usedAtrequired | string (date-time) | null | — |
usedFromIprequired | string | null | — |
revokedAtrequired | string (date-time) | null | — |
createdByrequired | string (uuid) | null | — |
createdByAccountIdrequired | string (uuid) | null | — |
labelrequired | string | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"state": "unused",
"expiresAt": "2026-03-02T09:00:00.000Z",
"usedAt": "2026-03-02T09:00:00.000Z",
"usedFromIp": "string",
"revokedAt": "2026-03-02T09:00:00.000Z",
"createdBy": "0b14e5a6-0b14-7b14-814e-0b14e5a60b14",
"createdByAccountId": "34bcf5dc-34bc-74bc-8bcf-34bcf5dc34bc",
"label": "string",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/tenants/{tenantId}/licenses
List every license issued to this tenant.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/licenses" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
[
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"jti": "string",
"issuedAt": "2026-03-02T09:00:00.000Z",
"expiresAt": "2026-03-02T09:00:00.000Z",
"lastValidatedAt": "2026-03-02T09:00:00.000Z",
"status": "valid",
"metadata": {},
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}
]Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{tenantId}/licenses
Issue a signed license for this tenant. The key is returned exactly once. Owner only; requires a step-up MFA check within the last 10 minutes.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
ttlDays | integer | 0–3650 · default: 365 |
Example
{
"ttlDays": 365
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/licenses" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"ttlDays": 365
}'Responses
| Name | Type | Constraints |
|---|---|---|
licenserequired | object | — |
keyrequired | string | — |
{
"license": {
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"jti": "string",
"issuedAt": "2026-03-02T09:00:00.000Z",
"expiresAt": "2026-03-02T09:00:00.000Z",
"lastValidatedAt": "2026-03-02T09:00:00.000Z",
"status": "valid",
"metadata": {},
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
},
"key": "string"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{tenantId}/licenses/{licenseId}/revoke
Revoke a license (key compromise / re-issue). Its heartbeats then answer 404, identically to an unknown license.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
licenseIdrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/licenses/f5f084e9-f5f0-75f0-8f08-f5f084e9f5f0/revoke" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
jtirequired | string | — |
issuedAtrequired | string (date-time) | — |
expiresAtrequired | string (date-time) | — |
lastValidatedAtrequired | string (date-time) | null | — |
statusrequired | enum: "valid" | "expired" | "locked" | "revoked" | — |
metadatarequired | object | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"jti": "string",
"issuedAt": "2026-03-02T09:00:00.000Z",
"expiresAt": "2026-03-02T09:00:00.000Z",
"lastValidatedAt": "2026-03-02T09:00:00.000Z",
"status": "valid",
"metadata": {},
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/tenants/{tenantId}/registry-credentials
List this tenant's registry credentials (usernames, timestamps — never a secret).
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/registry-credentials" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
[
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"username": "string",
"createdByUserId": "d630cadc-d630-7630-830c-d630cadcd630",
"lastUsedAt": "2026-03-02T09:00:00.000Z",
"revokedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}
]Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{tenantId}/registry-credentials
Create a registry credential for this tenant. The secret is returned exactly once. Owner only.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/registry-credentials" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
credentialrequired | object | — |
secretrequired | string | — |
{
"credential": {
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"username": "string",
"createdByUserId": "d630cadc-d630-7630-830c-d630cadcd630",
"lastUsedAt": "2026-03-02T09:00:00.000Z",
"revokedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
},
"secret": "string"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{tenantId}/registry-credentials/{credentialId}/revoke
Revoke a registry credential. Its next token request answers 401.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
credentialIdrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/registry-credentials/609aae45-609a-709a-89aa-609aae45609a/revoke" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
usernamerequired | string | — |
createdByUserIdrequired | string (uuid) | null | — |
lastUsedAtrequired | string (date-time) | null | — |
revokedAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"username": "string",
"createdByUserId": "d630cadc-d630-7630-830c-d630cadcd630",
"lastUsedAt": "2026-03-02T09:00:00.000Z",
"revokedAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{tenantId}/subscription
Set a tenant’s plan and/or billing period.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
planId | string (uuid) | — |
currentPeriodStart | string (date-time) | — |
currentPeriodEnd | string (date-time) | — |
Example
{
"planId": "744bf63f-744b-744b-84bf-744bf63f744b",
"currentPeriodStart": "2026-03-02T09:00:00.000Z",
"currentPeriodEnd": "2026-03-02T09:00:00.000Z"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/subscription" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"planId": "744bf63f-744b-744b-84bf-744bf63f744b",
"currentPeriodStart": "2026-03-02T09:00:00.000Z",
"currentPeriodEnd": "2026-03-02T09:00:00.000Z"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
planIdrequired | string (uuid) | — |
statusrequired | enum: "trialing" | "active" | "expired" | "suspended" | "cancelled" | — |
currentPeriodStartrequired | string (date-time) | — |
currentPeriodEndrequired | string (date-time) | — |
cancelledAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"planId": "744bf63f-744b-744b-84bf-744bf63f744b",
"status": "trialing",
"currentPeriodStart": "2026-03-02T09:00:00.000Z",
"currentPeriodEnd": "2026-03-02T09:00:00.000Z",
"cancelledAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{tenantId}/subscription/cancel
Cancel a tenant’s subscription.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/subscription/cancel" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
planIdrequired | string (uuid) | — |
statusrequired | enum: "trialing" | "active" | "expired" | "suspended" | "cancelled" | — |
currentPeriodStartrequired | string (date-time) | — |
currentPeriodEndrequired | string (date-time) | — |
cancelledAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"planId": "744bf63f-744b-744b-84bf-744bf63f744b",
"status": "trialing",
"currentPeriodStart": "2026-03-02T09:00:00.000Z",
"currentPeriodEnd": "2026-03-02T09:00:00.000Z",
"cancelledAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/tenants/{tenantId}/subscription/renew
Extend the billing period and set status back to active.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
tenantIdrequired | path | string | — |
Request body
| Name | Type | Constraints |
|---|---|---|
currentPeriodStart | string (date-time) | — |
currentPeriodEndrequired | string (date-time) | — |
Example
{
"currentPeriodStart": "2026-03-02T09:00:00.000Z",
"currentPeriodEnd": "2026-03-02T09:00:00.000Z"
}curl example
curl -X POST "https://your-institute.example/api/v1/platform/tenants/4332af8b-4332-7332-832a-4332af8b4332/subscription/renew" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"currentPeriodStart": "2026-03-02T09:00:00.000Z",
"currentPeriodEnd": "2026-03-02T09:00:00.000Z"
}'Responses
| Name | Type | Constraints |
|---|---|---|
idrequired | string (uuid) | — |
tenantIdrequired | string (uuid) | — |
planIdrequired | string (uuid) | — |
statusrequired | enum: "trialing" | "active" | "expired" | "suspended" | "cancelled" | — |
currentPeriodStartrequired | string (date-time) | — |
currentPeriodEndrequired | string (date-time) | — |
cancelledAtrequired | string (date-time) | null | — |
createdAtrequired | string (date-time) | — |
updatedAtrequired | string (date-time) | — |
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"tenantId": "4332af8b-4332-7332-832a-4332af8b4332",
"planId": "744bf63f-744b-744b-84bf-744bf63f744b",
"status": "trialing",
"currentPeriodStart": "2026-03-02T09:00:00.000Z",
"currentPeriodEnd": "2026-03-02T09:00:00.000Z",
"cancelledAt": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
GET /api/v1/platform/users
Search users globally (cursor-paginated).
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
cursor | query | string | — |
limit | query | integer | 1–100 · default: 25 |
search | query | string | 1–200 chars |
curl example
curl -X GET "https://your-institute.example/api/v1/platform/users" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
datarequired | array<object> | — |
nextCursorrequired | string | null | — |
{
"data": [
{
"id": "37386ae0-3738-7738-8386-37386ae03738",
"email": "ada.lovelace@example.com",
"emailVerifiedAt": "2026-03-02T09:00:00.000Z",
"fullName": "Ada Lovelace",
"phone": "+15551234567",
"locale": "ar",
"avatarFileId": "3561389f-3561-7561-8613-3561389f3561",
"status": "active",
"lastLoginAt": "2026-03-02T09:00:00.000Z",
"failedLoginCount": -9007199254740991,
"lockedUntil": "2026-03-02T09:00:00.000Z",
"createdAt": "2026-03-02T09:00:00.000Z",
"updatedAt": "2026-03-02T09:00:00.000Z"
}
],
"nextCursor": null
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/users/{id}/disable
Disable a user account and revoke every one of their sessions.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/users/37386ae0-3738-7738-8386-37386ae03738/disable" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
POST /api/v1/platform/users/{id}/enable
Re-enable a disabled user account.
Path & query parameters
| Name | In | Type | Constraints |
|---|---|---|---|
idrequired | path | string | — |
curl example
curl -X POST "https://your-institute.example/api/v1/platform/users/37386ae0-3738-7738-8386-37386ae03738/enable" \
-H "Authorization: Bearer $INSTITFLOW_API_KEY"Responses
| Name | Type | Constraints |
|---|---|---|
okrequired | enum: true | — |
{
"ok": true
}Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.
Returns the shared `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. Every code is listed in the Conventions guide.