Public API

API Keys & Webhooks

Manage secret/publishable API keys, webhook endpoints and deliveries, and the public (publishable-key-authenticated) registration endpoint used by the embeddable widget.

25 נקודות קצה

GET /api/v1/api-keys

List API keys (cursor-paginated). Never returns the full key value.

דורש אימותהרשאהintegration.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
cursor
querystring—
limit
queryinteger1–100 · default: 25

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "name": "Algebra I",
      "kind": "secret",
      "keyPrefix": "string",
      "permissions": [
        "string"
      ],
      "allowedOrigins": [
        "string"
      ],
      "rateLimitPerMin": 1,
      "effectiveRateLimitPerMin": 0,
      "lastUsedAt": "2026-03-02T09:00:00.000Z",
      "expiresAt": "2026-03-02T09:00:00.000Z",
      "revokedAt": "2026-03-02T09:00:00.000Z",
      "createdAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/api-keys

Create a public API key. The full key value is returned exactly once — store it now, it cannot be retrieved again.

דורש אימותהרשאהintegration.manage

גוף הבקשה

שםסוגמגבלות
nameחובה
string1–100 chars
kind
enum: "secret" | "publishable"default: "secret"
permissions
array<string>default: []
allowedOrigins
array<string>default: []
rateLimitPerMin
integer | null1–1000000
expiresAt
string (date-time)—

דוגמה

json
{
  "name": "Algebra I",
  "kind": "secret",
  "permissions": [
    "string"
  ],
  "allowedOrigins": [
    "string"
  ],
  "rateLimitPerMin": 1,
  "expiresAt": "2026-03-02T09:00:00.000Z"
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/api-keys" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Algebra I",
    "kind": "secret",
    "permissions": [
      "string"
    ],
    "allowedOrigins": [
      "string"
    ],
    "rateLimitPerMin": 1,
    "expiresAt": "2026-03-02T09:00:00.000Z"
  }'

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
nameחובה
string≥1 chars
kindחובה
enum: "secret" | "publishable"—
keyPrefixחובה
string≥1 chars
permissionsחובה
array<string>—
allowedOriginsחובה
array<string>—
rateLimitPerMinחובה
integer | null≤9007199254740991
effectiveRateLimitPerMinחובה
integer0–9007199254740991
lastUsedAtחובה
string (date-time) | null≥1 chars
expiresAtחובה
string (date-time) | null≥1 chars
revokedAtחובה
string (date-time) | null≥1 chars
createdAtחובה
string (date-time)—
keyחובה
string≥1 chars
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "name": "Algebra I",
  "kind": "secret",
  "keyPrefix": "string",
  "permissions": [
    "string"
  ],
  "allowedOrigins": [
    "string"
  ],
  "rateLimitPerMin": 1,
  "effectiveRateLimitPerMin": 0,
  "lastUsedAt": "2026-03-02T09:00:00.000Z",
  "expiresAt": "2026-03-02T09:00:00.000Z",
  "revokedAt": "2026-03-02T09:00:00.000Z",
  "createdAt": "2026-03-02T09:00:00.000Z",
  "key": "string"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

DELETE /api/v1/api-keys/{id}

Revoke an API key. Idempotent — revoking an already-revoked key is a no-op.

דורש אימותהרשאהintegration.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

דוגמה עם curl

curl
curl -X DELETE "https://your-institute.example/api/v1/api-keys/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
nameחובה
string≥1 chars
kindחובה
enum: "secret" | "publishable"—
keyPrefixחובה
string≥1 chars
permissionsחובה
array<string>—
allowedOriginsחובה
array<string>—
rateLimitPerMinחובה
integer | null≤9007199254740991
effectiveRateLimitPerMinחובה
integer0–9007199254740991
lastUsedAtחובה
string (date-time) | null≥1 chars
expiresAtחובה
string (date-time) | null≥1 chars
revokedAtחובה
string (date-time) | null≥1 chars
createdAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "name": "Algebra I",
  "kind": "secret",
  "keyPrefix": "string",
  "permissions": [
    "string"
  ],
  "allowedOrigins": [
    "string"
  ],
  "rateLimitPerMin": 1,
  "effectiveRateLimitPerMin": 0,
  "lastUsedAt": "2026-03-02T09:00:00.000Z",
  "expiresAt": "2026-03-02T09:00:00.000Z",
  "revokedAt": "2026-03-02T09:00:00.000Z",
  "createdAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

PATCH /api/v1/api-keys/{id}

Change a key’s per-minute rate limit. `null` restores the plan/global default; a value above the plan’s ceiling is rejected with 422. Takes effect immediately — the auth cache is evicted.

דורש אימותהרשאהintegration.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

גוף הבקשה

שםסוגמגבלות
rateLimitPerMinחובה
integer | null1–1000000

דוגמה

json
{
  "rateLimitPerMin": 1
}

דוגמה עם curl

curl
curl -X PATCH "https://your-institute.example/api/v1/api-keys/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "rateLimitPerMin": 1
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
nameחובה
string≥1 chars
kindחובה
enum: "secret" | "publishable"—
keyPrefixחובה
string≥1 chars
permissionsחובה
array<string>—
allowedOriginsחובה
array<string>—
rateLimitPerMinחובה
integer | null≤9007199254740991
effectiveRateLimitPerMinחובה
integer0–9007199254740991
lastUsedAtחובה
string (date-time) | null≥1 chars
expiresAtחובה
string (date-time) | null≥1 chars
revokedAtחובה
string (date-time) | null≥1 chars
createdAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "name": "Algebra I",
  "kind": "secret",
  "keyPrefix": "string",
  "permissions": [
    "string"
  ],
  "allowedOrigins": [
    "string"
  ],
  "rateLimitPerMin": 1,
  "effectiveRateLimitPerMin": 0,
  "lastUsedAt": "2026-03-02T09:00:00.000Z",
  "expiresAt": "2026-03-02T09:00:00.000Z",
  "revokedAt": "2026-03-02T09:00:00.000Z",
  "createdAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/leads

List leads captured by the public surface (cursor-paginated), filterable by `status`, `source` and `courseId`.

דורש אימותהרשאהstudents.read

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
cursor
querystring—
limit
queryinteger1–100 · default: 25
status
queryenum: "new" | "contacted" | "converted" | "discarded" | "rejected"—
source
queryenum: "widget" | "api" | "join_link"—
courseId
querystring (uuid)—

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "source": "widget",
      "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
      "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
      "fullName": "Ada Lovelace",
      "phone": "+15551234567",
      "email": "ada.lovelace@example.com",
      "message": "string",
      "locale": "ar",
      "status": "new",
      "convertedStudentId": "1f357c81-1f35-7f35-8357-1f357c811f35",
      "joinLinkLabel": "string",
      "suggestedStudentId": "0757ecaa-0757-7757-857e-0757ecaa0757",
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/leads/{id}

Get one lead by id, including the submitter’s message and contact details.

דורש אימותהרשאהstudents.read

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/leads/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
sourceחובה
enum: "widget" | "api" | "join_link"—
courseIdחובה
string (uuid) | null—
groupIdחובה
string (uuid) | null—
fullNameחובה
string—
phoneחובה
string | null—
emailחובה
string | null—
messageחובה
string | null—
localeחובה
enum: "ar" | "en" | "he"—
statusחובה
enum: "new" | "contacted" | "converted" | "discarded" | "rejected"—
convertedStudentIdחובה
string (uuid) | null—
joinLinkLabelחובה
string | null—
suggestedStudentIdחובה
string (uuid) | null—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "source": "widget",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
  "fullName": "Ada Lovelace",
  "phone": "+15551234567",
  "email": "ada.lovelace@example.com",
  "message": "string",
  "locale": "ar",
  "status": "new",
  "convertedStudentId": "1f357c81-1f35-7f35-8357-1f357c811f35",
  "joinLinkLabel": "string",
  "suggestedStudentId": "0757ecaa-0757-7757-857e-0757ecaa0757",
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

PATCH /api/v1/leads/{id}

Change a lead’s status (`new`, `contacted`, `discarded`). `converted` is reachable only through `POST /leads/:id/convert`, which creates the student it points at.

דורש אימותהרשאהstudents.write

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

גוף הבקשה

שםסוגמגבלות
statusחובה
enum: "new" | "contacted" | "discarded"—

דוגמה

json
{
  "status": "new"
}

דוגמה עם curl

curl
curl -X PATCH "https://your-institute.example/api/v1/leads/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "status": "new"
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
sourceחובה
enum: "widget" | "api" | "join_link"—
courseIdחובה
string (uuid) | null—
groupIdחובה
string (uuid) | null—
fullNameחובה
string—
phoneחובה
string | null—
emailחובה
string | null—
messageחובה
string | null—
localeחובה
enum: "ar" | "en" | "he"—
statusחובה
enum: "new" | "contacted" | "converted" | "discarded" | "rejected"—
convertedStudentIdחובה
string (uuid) | null—
joinLinkLabelחובה
string | null—
suggestedStudentIdחובה
string (uuid) | null—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "source": "widget",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
  "fullName": "Ada Lovelace",
  "phone": "+15551234567",
  "email": "ada.lovelace@example.com",
  "message": "string",
  "locale": "ar",
  "status": "new",
  "convertedStudentId": "1f357c81-1f35-7f35-8357-1f357c811f35",
  "joinLinkLabel": "string",
  "suggestedStudentId": "0757ecaa-0757-7757-857e-0757ecaa0757",
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/leads/{id}/accept

Approve a join request: create a student from the account (`mode: new`, with branch and name) or link it to an existing student (`mode: link`), link the account, enrol into the join link's group when it named one, and tell the control plane. Enrolment problems are reported, not raised. Only a lead from a join link; 409 once decided.

דורש אימותהרשאהstudents.write

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

גוף הבקשה

אין.

דוגמה

json
"value"

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/leads/37386ae0-3738-7738-8386-37386ae03738/accept" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '"value"'

תשובות

201
שםסוגמגבלות
leadחובה
object—
studentIdחובה
string (uuid)—
enrollmentחובה
enum: "enrolled" | "none" | "skipped"—
enrollmentProblemחובה
string | null—
json
{
  "lead": {
    "id": "37386ae0-3738-7738-8386-37386ae03738",
    "source": "widget",
    "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
    "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
    "fullName": "Ada Lovelace",
    "phone": "+15551234567",
    "email": "ada.lovelace@example.com",
    "message": "string",
    "locale": "ar",
    "status": "new",
    "convertedStudentId": "1f357c81-1f35-7f35-8357-1f357c811f35",
    "joinLinkLabel": "string",
    "suggestedStudentId": "0757ecaa-0757-7757-857e-0757ecaa0757",
    "createdAt": "2026-03-02T09:00:00.000Z",
    "updatedAt": "2026-03-02T09:00:00.000Z"
  },
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "enrollment": "enrolled",
  "enrollmentProblem": "string"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/leads/{id}/convert

Promote a lead to a real student. Creates the student through the normal students path (student-number allocation, audit, `student.created`), then links it back as the lead’s `convertedStudentId`. `firstName`/`lastName` default to a split of the submitted full name.

דורש אימותהרשאהstudents.write

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

גוף הבקשה

שםסוגמגבלות
branchIdחובה
string (uuid)—
firstName
string1–100 chars
lastName
string1–100 chars

דוגמה

json
{
  "branchId": "390b8975-390b-790b-80b8-390b8975390b",
  "firstName": "Ada",
  "lastName": "Lovelace"
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/leads/37386ae0-3738-7738-8386-37386ae03738/convert" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "branchId": "390b8975-390b-790b-80b8-390b8975390b",
    "firstName": "Ada",
    "lastName": "Lovelace"
  }'

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
sourceחובה
enum: "widget" | "api" | "join_link"—
courseIdחובה
string (uuid) | null—
groupIdחובה
string (uuid) | null—
fullNameחובה
string—
phoneחובה
string | null—
emailחובה
string | null—
messageחובה
string | null—
localeחובה
enum: "ar" | "en" | "he"—
statusחובה
enum: "new" | "contacted" | "converted" | "discarded" | "rejected"—
convertedStudentIdחובה
string (uuid) | null—
joinLinkLabelחובה
string | null—
suggestedStudentIdחובה
string (uuid) | null—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "source": "widget",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
  "fullName": "Ada Lovelace",
  "phone": "+15551234567",
  "email": "ada.lovelace@example.com",
  "message": "string",
  "locale": "ar",
  "status": "new",
  "convertedStudentId": "1f357c81-1f35-7f35-8357-1f357c811f35",
  "joinLinkLabel": "string",
  "suggestedStudentId": "0757ecaa-0757-7757-857e-0757ecaa0757",
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/leads/{id}/reject

Reject a join request. The lead is kept as `rejected` for the record; the person sees the decision when they open the link again. 409 once decided.

דורש אימותהרשאהstudents.write

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/leads/37386ae0-3738-7738-8386-37386ae03738/reject" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
sourceחובה
enum: "widget" | "api" | "join_link"—
courseIdחובה
string (uuid) | null—
groupIdחובה
string (uuid) | null—
fullNameחובה
string—
phoneחובה
string | null—
emailחובה
string | null—
messageחובה
string | null—
localeחובה
enum: "ar" | "en" | "he"—
statusחובה
enum: "new" | "contacted" | "converted" | "discarded" | "rejected"—
convertedStudentIdחובה
string (uuid) | null—
joinLinkLabelחובה
string | null—
suggestedStudentIdחובה
string (uuid) | null—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "source": "widget",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
  "fullName": "Ada Lovelace",
  "phone": "+15551234567",
  "email": "ada.lovelace@example.com",
  "message": "string",
  "locale": "ar",
  "status": "new",
  "convertedStudentId": "1f357c81-1f35-7f35-8357-1f357c811f35",
  "joinLinkLabel": "string",
  "suggestedStudentId": "0757ecaa-0757-7757-857e-0757ecaa0757",
  "createdAt": "2026-03-02T09:00:00.000Z",
  "updatedAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/public/branches

List the institute’s active branches (name, address, phone) for a “where we are” page. Auth: publishable key via `X-Api-Key`.

דורש אימותהרשאהללא הרשאה נוספת

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
cursor
querystring—
limit
queryinteger1–100 · default: 25

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "name": "Algebra I",
      "address": {},
      "phone": "+15551234567"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/public/courses

List the institute’s public courses (cursor-paginated), filterable by `category`, `level` and `language`. Auth: publishable key via `X-Api-Key`. Returns 404 when the institute has not enabled its public catalogue.

דורש אימותהרשאהללא הרשאה נוספת

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
cursor
querystring—
limit
queryinteger1–100 · default: 25
category
querystring1–200 chars
level
querystring1–60 chars
language
querystring1–60 chars

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "name": "Algebra I",
      "description": "A short, human-readable description.",
      "category": "string",
      "level": "string",
      "language": "string",
      "price": {
        "amountMinor": 12000,
        "currency": "ILS"
      },
      "isActive": true
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/public/courses/{id}

One public course plus its open groups (schedule pattern, start date, and a bucketed `seatsRemaining` hint — never an exact count, never a teacher name). A course that is not public returns the same 404 as one that does not exist.

דורש אימותהרשאהללא הרשאה נוספת

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/public/courses/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
nameחובה
string—
descriptionחובה
string | null—
categoryחובה
string | null—
levelחובה
string | null—
languageחובה
string | null—
priceחובה
object | null—
isActiveחובה
boolean—
groupsחובה
array<object>—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "name": "Algebra I",
  "description": "A short, human-readable description.",
  "category": "string",
  "level": "string",
  "language": "string",
  "price": {
    "amountMinor": 12000,
    "currency": "ILS"
  },
  "isActive": true,
  "groups": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "name": "Algebra I",
      "startDate": "2026-03-02",
      "endDate": "2026-03-02",
      "schedule": [
        {
          "weekday": 0,
          "startTime": "string",
          "endTime": "string"
        }
      ],
      "seatsRemaining": "plenty"
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/public/leads

Submit a contact-form lead. Writes a `leads` row, never a student — a staff member promotes it with `POST /leads/:id/convert`. Auth: publishable key via `X-Api-Key` header or `apiKey` body field. Requires `captchaToken` when the institute has configured a CAPTCHA site key.

דורש אימותהרשאהללא הרשאה נוספת

גוף הבקשה

שםסוגמגבלות
apiKey
string≥1 chars
fullNameחובה
string1–200 chars
phone
string—
email
string (email)0–320 chars
message
string1–2000 chars
courseId
string (uuid)—
groupId
string (uuid)—
locale
enum: "ar" | "en" | "he"default: "ar"
captchaToken
string1–4000 chars

דוגמה

json
{
  "apiKey": "string",
  "fullName": "Ada Lovelace",
  "phone": "+15551234567",
  "email": "ada.lovelace@example.com",
  "message": "string",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
  "locale": "ar",
  "captchaToken": "string"
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/public/leads" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "apiKey": "string",
    "fullName": "Ada Lovelace",
    "phone": "+15551234567",
    "email": "ada.lovelace@example.com",
    "message": "string",
    "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
    "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
    "locale": "ar",
    "captchaToken": "string"
  }'

תשובות

201
שםסוגמגבלות
okחובה
enum: true—
json
{
  "ok": true
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/public/registrations

Create a lead student + guardian from the embeddable widget. Auth: publishable key via `X-Api-Key` header or `apiKey` body field. An institute that has switched `integration.registrationsToLeads` on gets a `leads` row instead, and the response carries `leadId` with `studentId`/`guardianId` null.

דורש אימותהרשאהללא הרשאה נוספת

גוף הבקשה

שםסוגמגבלות
apiKey
string≥1 chars
studentחובה
object—
guardianחובה
object—
courseInterest
string1–200 chars
courseId
string (uuid)—
groupId
string (uuid)—
captchaToken
string1–4000 chars
locale
enum: "ar" | "en" | "he"—

דוגמה

json
{
  "apiKey": "string",
  "student": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "phone": "+15551234567",
    "email": "ada.lovelace@example.com"
  },
  "guardian": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "phone": "+15551234567",
    "email": "ada.lovelace@example.com"
  },
  "courseInterest": "string",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
  "captchaToken": "string",
  "locale": "ar"
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/public/registrations" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "apiKey": "string",
    "student": {
      "firstName": "Ada",
      "lastName": "Lovelace",
      "phone": "+15551234567",
      "email": "ada.lovelace@example.com"
    },
    "guardian": {
      "firstName": "Ada",
      "lastName": "Lovelace",
      "phone": "+15551234567",
      "email": "ada.lovelace@example.com"
    },
    "courseInterest": "string",
    "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
    "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
    "captchaToken": "string",
    "locale": "ar"
  }'

תשובות

201
שםסוגמגבלות
okחובה
enum: true—
studentIdחובה
string (uuid) | null—
guardianIdחובה
string (uuid) | null—
leadIdחובה
string (uuid) | null—
json
{
  "ok": true,
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "guardianId": "69993220-6999-7999-8993-699932206999",
  "leadId": "af1c3d42-af1c-7f1c-81c3-af1c3d42af1c"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/webhooks

List webhook endpoints (cursor-paginated). Never returns the signing secret.

דורש אימותהרשאהintegration.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
cursor
querystring—
limit
queryinteger1–100 · default: 25

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "url": "https://example.com/webhooks/institflow",
      "events": [
        "string"
      ],
      "isActive": true,
      "failureCount": 0,
      "disabledAt": "2026-03-02T09:00:00.000Z",
      "previousSecretExpiresAt": "2026-03-02T09:00:00.000Z",
      "createdAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/webhooks

Register a webhook endpoint. The signing secret is returned exactly once.

דורש אימותהרשאהintegration.manage

גוף הבקשה

שםסוגמגבלות
urlחובה
string—
eventsחובה
array<enum: "student.created" | "student.updated" | "student.status_changed" | "enrollment.created" | "enrollment.dropped" | "session.cancelled" | "attendance.marked" | "student.absent" | "exam.published" | "progress_report.sent" | "invoice.issued" | "invoice.overdue" | "invoice.reminder_requested" | "payment.recorded" | "billing.payment_proof.submitted" | "billing.payment_proof.reviewed" | "member.invited" | "lesson.published" | "lesson.completed" | "course.completed" | "course_enrollment.created" | "course_enrollment.dropped" | "lesson_file.added" | "lesson_file.updated" | "lesson_file.reordered" | "lesson_file.removed" | "lesson.audience_changed" | "lesson_task.saved" | "lesson_task.removed" | "reminder.dispatched" | "notification_type_preference.changed" | "web_push.subscribed" | "web_push.unsubscribed" | "notification_rule.updated" | "notification_rule.reset" | "item_reminder_mode.changed" | "assignment.published" | "assignment.submitted" | "assignment.graded" | "quiz.published" | "quiz.submitted" | "quiz.graded" | "subscription.expiring" | "subscription.expired" | "tenant.locked" | "tenant.unlocked" | "license.signal" | "install.update_failed" | "install.updater_key_bound" | "relay.install_rekeyed" | "lead.created" | "join_link.created" | "join_link.status_changed" | "join_link.redeemed" | "join_request.approved" | "join_request.rejected" | "portal_invite.declined" | "webhook_endpoint.secret_rotated" | "support.report_received" | "support.report_status_changed" | "support.report_replied" | "support_submission.created" | "support_submission.status_changed" | "relay.install_updater_key_bound">—

דוגמה

json
{
  "url": "https://example.com/webhooks/institflow",
  "events": [
    "student.created"
  ]
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/webhooks" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://example.com/webhooks/institflow",
    "events": [
      "student.created"
    ]
  }'

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
urlחובה
string≥1 chars
eventsחובה
array<string>—
isActiveחובה
boolean—
failureCountחובה
integer0–9007199254740991
disabledAtחובה
string (date-time) | null≥1 chars
previousSecretExpiresAtחובה
string (date-time) | null≥1 chars
createdAtחובה
string (date-time)—
secretחובה
string≥1 chars
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "url": "https://example.com/webhooks/institflow",
  "events": [
    "string"
  ],
  "isActive": true,
  "failureCount": 0,
  "disabledAt": "2026-03-02T09:00:00.000Z",
  "previousSecretExpiresAt": "2026-03-02T09:00:00.000Z",
  "createdAt": "2026-03-02T09:00:00.000Z",
  "secret": "string"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

DELETE /api/v1/webhooks/{id}

Delete a webhook endpoint (its delivery history is deleted with it).

דורש אימותהרשאהintegration.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

דוגמה עם curl

curl
curl -X DELETE "https://your-institute.example/api/v1/webhooks/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200The webhook endpoint was deleted.
שםסוגמגבלות
okחובה
enum: true—
json
{
  "ok": true
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/webhooks/{id}

Get one webhook endpoint by id.

דורש אימותהרשאהintegration.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/webhooks/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
urlחובה
string≥1 chars
eventsחובה
array<string>—
isActiveחובה
boolean—
failureCountחובה
integer0–9007199254740991
disabledAtחובה
string (date-time) | null≥1 chars
previousSecretExpiresAtחובה
string (date-time) | null≥1 chars
createdAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "url": "https://example.com/webhooks/institflow",
  "events": [
    "string"
  ],
  "isActive": true,
  "failureCount": 0,
  "disabledAt": "2026-03-02T09:00:00.000Z",
  "previousSecretExpiresAt": "2026-03-02T09:00:00.000Z",
  "createdAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

PATCH /api/v1/webhooks/{id}

Update a webhook endpoint (url, subscribed events, active state).

דורש אימותהרשאהintegration.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

גוף הבקשה

שםסוגמגבלות
url
string—
events
array<enum: "student.created" | "student.updated" | "student.status_changed" | "enrollment.created" | "enrollment.dropped" | "session.cancelled" | "attendance.marked" | "student.absent" | "exam.published" | "progress_report.sent" | "invoice.issued" | "invoice.overdue" | "invoice.reminder_requested" | "payment.recorded" | "billing.payment_proof.submitted" | "billing.payment_proof.reviewed" | "member.invited" | "lesson.published" | "lesson.completed" | "course.completed" | "course_enrollment.created" | "course_enrollment.dropped" | "lesson_file.added" | "lesson_file.updated" | "lesson_file.reordered" | "lesson_file.removed" | "lesson.audience_changed" | "lesson_task.saved" | "lesson_task.removed" | "reminder.dispatched" | "notification_type_preference.changed" | "web_push.subscribed" | "web_push.unsubscribed" | "notification_rule.updated" | "notification_rule.reset" | "item_reminder_mode.changed" | "assignment.published" | "assignment.submitted" | "assignment.graded" | "quiz.published" | "quiz.submitted" | "quiz.graded" | "subscription.expiring" | "subscription.expired" | "tenant.locked" | "tenant.unlocked" | "license.signal" | "install.update_failed" | "install.updater_key_bound" | "relay.install_rekeyed" | "lead.created" | "join_link.created" | "join_link.status_changed" | "join_link.redeemed" | "join_request.approved" | "join_request.rejected" | "portal_invite.declined" | "webhook_endpoint.secret_rotated" | "support.report_received" | "support.report_status_changed" | "support.report_replied" | "support_submission.created" | "support_submission.status_changed" | "relay.install_updater_key_bound">—
isActive
boolean—

דוגמה

json
{
  "url": "https://example.com/webhooks/institflow",
  "events": [
    "student.created"
  ],
  "isActive": true
}

דוגמה עם curl

curl
curl -X PATCH "https://your-institute.example/api/v1/webhooks/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://example.com/webhooks/institflow",
    "events": [
      "student.created"
    ],
    "isActive": true
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
urlחובה
string≥1 chars
eventsחובה
array<string>—
isActiveחובה
boolean—
failureCountחובה
integer0–9007199254740991
disabledAtחובה
string (date-time) | null≥1 chars
previousSecretExpiresAtחובה
string (date-time) | null≥1 chars
createdAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "url": "https://example.com/webhooks/institflow",
  "events": [
    "string"
  ],
  "isActive": true,
  "failureCount": 0,
  "disabledAt": "2026-03-02T09:00:00.000Z",
  "previousSecretExpiresAt": "2026-03-02T09:00:00.000Z",
  "createdAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/webhooks/{id}/deliveries

List an endpoint’s delivery history (cursor-paginated, optional status filter).

דורש אימותהרשאהintegration.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—
cursor
querystring—
limit
queryinteger1–100 · default: 25
status
queryenum: "queued" | "delivered" | "failed" | "disabled"—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/webhooks/37386ae0-3738-7738-8386-37386ae03738/deliveries" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "endpointId": "e6542a51-e654-7654-8542-e6542a51e654",
      "eventId": "8f3712f2-8f37-7f37-8371-8f3712f28f37",
      "eventType": "string",
      "status": "queued",
      "attempts": 0,
      "lastStatusCode": -9007199254740991,
      "responseExcerpt": "string",
      "nextAttemptAt": "2026-03-02T09:00:00.000Z",
      "deliveredAt": "2026-03-02T09:00:00.000Z",
      "createdAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "nextCursor": null
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/replay

Replay a delivery: resets it to `queued` and enqueues an immediate send attempt.

דורש אימותהרשאהintegration.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—
deliveryIdחובה
pathstring—

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/webhooks/37386ae0-3738-7738-8386-37386ae03738/deliveries/67cebe50-67ce-77ce-8ceb-67cebe5067ce/replay" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
endpointIdחובה
string (uuid)—
eventIdחובה
string (uuid)—
eventTypeחובה
string≥1 chars
statusחובה
enum: "queued" | "delivered" | "failed" | "disabled"—
attemptsחובה
integer0–9007199254740991
lastStatusCodeחובה
integer | null-9007199254740991–9007199254740991
responseExcerptחובה
string | null≥1 chars
nextAttemptAtחובה
string (date-time) | null≥1 chars
deliveredAtחובה
string (date-time) | null≥1 chars
createdAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "endpointId": "e6542a51-e654-7654-8542-e6542a51e654",
  "eventId": "8f3712f2-8f37-7f37-8371-8f3712f28f37",
  "eventType": "string",
  "status": "queued",
  "attempts": 0,
  "lastStatusCode": -9007199254740991,
  "responseExcerpt": "string",
  "nextAttemptAt": "2026-03-02T09:00:00.000Z",
  "deliveredAt": "2026-03-02T09:00:00.000Z",
  "createdAt": "2026-03-02T09:00:00.000Z"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/webhooks/{id}/rotate-secret

Rotate the signing secret. The new secret is returned exactly once; the endpoint keeps its id and delivery history. For `overlapSec` (default 24 h, max 7 days) every delivery carries two `v1=` signatures — old and new — so you can redeploy without dropping an event. Send `overlapSec: 0` to retire the old secret immediately.

דורש אימותהרשאהintegration.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

גוף הבקשה

שםסוגמגבלות
overlapSec
integer0–604800

דוגמה

json
{
  "overlapSec": 0
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/webhooks/37386ae0-3738-7738-8386-37386ae03738/rotate-secret" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "overlapSec": 0
  }'

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
urlחובה
string≥1 chars
eventsחובה
array<string>—
isActiveחובה
boolean—
failureCountחובה
integer0–9007199254740991
disabledAtחובה
string (date-time) | null≥1 chars
previousSecretExpiresAtחובה
string (date-time) | null≥1 chars
createdAtחובה
string (date-time)—
secretחובה
string≥1 chars
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "url": "https://example.com/webhooks/institflow",
  "events": [
    "string"
  ],
  "isActive": true,
  "failureCount": 0,
  "disabledAt": "2026-03-02T09:00:00.000Z",
  "previousSecretExpiresAt": "2026-03-02T09:00:00.000Z",
  "createdAt": "2026-03-02T09:00:00.000Z",
  "secret": "string"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/webhooks/{id}/test

Send a signed test ping to the endpoint immediately (not persisted as a delivery).

דורש אימותהרשאהintegration.manage

פרמטרים של הנתיב והשאילתה

שםמיקוםסוגמגבלות
idחובה
pathstring—

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/webhooks/37386ae0-3738-7738-8386-37386ae03738/test" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

201
שםסוגמגבלות
okחובה
boolean—
statusCodeחובה
integer | null-9007199254740991–9007199254740991
responseExcerptחובה
string | null≥1 chars
json
{
  "ok": true,
  "statusCode": -9007199254740991,
  "responseExcerpt": "string"
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

402The tenant’s subscription or license is locked (`PAYMENT_REQUIRED`, `SUBSCRIPTION_SUSPENDED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

428An API-key caller must send an `Idempotency-Key` header (`IDEMPOTENCY_KEY_REQUIRED`).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/webhooks/events

The catalogue of subscribable webhook events with each one’s payload fields. No authentication — these are the exact strings `POST /api/v1/webhooks` accepts in `events[]`.

ללא אימותהרשאהציבורית

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
json
{
  "data": [
    {
      "type": "string",
      "description": "A short, human-readable description.",
      "fields": [
        "string"
      ]
    }
  ]
}
400The request could not be read at all — unparseable body, unusable content type, oversized payload (`MALFORMED_REQUEST`). Never a schema failure: those are 422.

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

422The request was read but its content is not acceptable: body/query/path/header failed schema validation (`VALIDATION_ERROR`, with `details.issues`), or a domain rule rejected a well-formed value (`VIDEO_URL_INVALID`, …).

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.

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

מחזירה את מעטפת השגיאה המשותפת `ErrorEnvelope` — `{ error: { code, message, requestId, details? } }`. כל הקודים מפורטים במדריך המוסכמות.