curriculum

Curriculum & Video

Course sections and lessons, lesson video links and their playback tokens, per-student course access grants, and progress tracking.

61 נקודות קצה

PATCH /api/v1/assignments/{lessonId}

Update an assignment’s own fields (instructions, due date, scoring, submission kinds). Lesson-shared fields (title, section, drip gate) go through `PATCH /lessons/:id`.

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

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

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

גוף הבקשה

שםסוגמגבלות
instructionsMd
enum: "" | string | null—
dueAt
string (date-time) | null—
maxScore
number0–1000
allowLate
boolean—
submissionKinds
array<enum: "text" | "file" | "link">—

דוגמה

json
{
  "instructionsMd": "",
  "dueAt": "2026-03-02T09:00:00.000Z",
  "maxScore": 0,
  "allowLate": true,
  "submissionKinds": [
    "text"
  ]
}

דוגמה עם curl

curl
curl -X PATCH "https://your-institute.example/api/v1/assignments/3d477cf4-3d47-7d47-8477-3d477cf43d47" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "instructionsMd": "",
    "dueAt": "2026-03-02T09:00:00.000Z",
    "maxScore": 0,
    "allowLate": true,
    "submissionKinds": [
      "text"
    ]
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
courseIdחובה
string (uuid)—
sectionIdחובה
string (uuid)—
titleחובה
string≥1 chars
summaryחובה
string | null≥1 chars
contentMdחובה
string | null≥1 chars
kindחובה
enum: "lesson" | "assignment" | "quiz"—
statusחובה
enum: "draft" | "published"—
publishedAtחובה
string (date-time) | null—
availableFromחובה
string (date-time) | null—
availableAfterDaysחובה
integer | null-9007199254740991–9007199254740991
estimatedMinutesחובה
integer | null-9007199254740991–9007199254740991
sortOrderחובה
integer-9007199254740991–9007199254740991
videoחובה
unknown | null—
assignmentחובה
unknown | null—
quizחובה
unknown | null—
audienceחובה
LessonAudience—
reminderModeחובה
enum: "inherit" | "on" | "off"—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "title": "Midterm Exam",
  "summary": "string",
  "contentMd": "string",
  "kind": "lesson",
  "status": "draft",
  "publishedAt": "2026-03-02T09:00:00.000Z",
  "availableFrom": "2026-03-02T09:00:00.000Z",
  "availableAfterDays": -9007199254740991,
  "estimatedMinutes": -9007199254740991,
  "sortOrder": -9007199254740991,
  "video": "value",
  "assignment": "value",
  "quiz": "value",
  "audience": {
    "restricted": true,
    "groups": [
      {
        "id": "37386ae0-3738-7738-8386-37386ae03738",
        "name": "Algebra I"
      }
    ],
    "hidden": true
  },
  "reminderMode": "inherit",
  "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/assignments/{lessonId}/publish-to-gradebook

Publish every currently-graded submission into the gradebook as a `homework` exam per group (ق-33) — one click, upserts on repeat.

דורש אימותהרשאהcurriculum.assignments.grade

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

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

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/assignments/3d477cf4-3d47-7d47-8477-3d477cf43d47/publish-to-gradebook" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
publishedחובה
array<object>—
skippedחובה
array<object>—
json
{
  "published": [
    {
      "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
      "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
      "examId": "6c140414-6c14-7c14-8140-6c1404146c14",
      "score": 1
    }
  ],
  "skipped": [
    {
      "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
      "reason": "no_group"
    }
  ]
}
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/assignments/{lessonId}/submissions

List an assignment’s submissions (cursor-paginated, optional status filter).

דורש אימותהרשאהcurriculum.assignments.grade

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

שםמיקוםסוגמגבלות
lessonIdחובה
pathstring—
cursor
querystring—
limit
queryinteger1–100 · default: 25
status
queryenum: "submitted" | "late" | "returned" | "graded"—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/assignments/3d477cf4-3d47-7d47-8477-3d477cf43d47/submissions" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "assignmentId": "c41b0f8d-c41b-741b-81b0-c41b0f8dc41b",
      "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
      "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
      "submittedAt": "2026-03-02T09:00:00.000Z",
      "textMd": "string",
      "link": "string",
      "files": [
        {
          "id": "37386ae0-3738-7738-8386-37386ae03738",
          "originalName": "string",
          "mimeType": "string",
          "sizeBytes": 0,
          "downloadUrl": "string",
          "downloadUrlExpiresAt": "2026-03-02T09:00:00.000Z"
        }
      ],
      "status": "submitted",
      "score": 1,
      "maxScore": 1,
      "feedbackMd": "string",
      "gradedByUserId": "71e16c27-71e1-71e1-8e16-71e16c2771e1",
      "gradedByName": "string",
      "gradedAt": "2026-03-02T09:00:00.000Z",
      "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/assignments/{lessonId}/submissions/{submissionId}/grade

Grade a submission (score ≤ the assignment’s max score, optional feedback). Emits `assignment.graded`.

דורש אימותהרשאהcurriculum.assignments.grade

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

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

גוף הבקשה

שםסוגמגבלות
scoreחובה
number≥0
feedbackMd
enum: "" | string | null—

דוגמה

json
{
  "score": 0,
  "feedbackMd": ""
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/assignments/3d477cf4-3d47-7d47-8477-3d477cf43d47/submissions/a396314c-a396-7396-8963-a396314ca396/grade" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "score": 0,
    "feedbackMd": ""
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
assignmentIdחובה
string (uuid)—
lessonIdחובה
string (uuid)—
studentIdחובה
string (uuid)—
submittedAtחובה
string (date-time)—
textMdחובה
string | null≥1 chars
linkחובה
string | null—
filesחובה
array<SubmissionFile>—
statusחובה
enum: "submitted" | "late" | "returned" | "graded"—
scoreחובה
number | null—
maxScoreחובה
number—
feedbackMdחובה
string | null≥1 chars
gradedByUserIdחובה
string (uuid) | null—
gradedByNameחובה
string | null≥1 chars
gradedAtחובה
string (date-time) | null—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "assignmentId": "c41b0f8d-c41b-741b-81b0-c41b0f8dc41b",
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "submittedAt": "2026-03-02T09:00:00.000Z",
  "textMd": "string",
  "link": "string",
  "files": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "originalName": "string",
      "mimeType": "string",
      "sizeBytes": 0,
      "downloadUrl": "string",
      "downloadUrlExpiresAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "status": "submitted",
  "score": 1,
  "maxScore": 1,
  "feedbackMd": "string",
  "gradedByUserId": "71e16c27-71e1-71e1-8e16-71e16c2771e1",
  "gradedByName": "string",
  "gradedAt": "2026-03-02T09:00:00.000Z",
  "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/assignments/{lessonId}/submissions/{submissionId}/return

Send a submission back for revision (clears any earlier grade).

דורש אימותהרשאהcurriculum.assignments.grade

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

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

גוף הבקשה

שםסוגמגבלות
feedbackMd
enum: "" | string | null—

דוגמה

json
{
  "feedbackMd": ""
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/assignments/3d477cf4-3d47-7d47-8477-3d477cf43d47/submissions/a396314c-a396-7396-8963-a396314ca396/return" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "feedbackMd": ""
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
assignmentIdחובה
string (uuid)—
lessonIdחובה
string (uuid)—
studentIdחובה
string (uuid)—
submittedAtחובה
string (date-time)—
textMdחובה
string | null≥1 chars
linkחובה
string | null—
filesחובה
array<SubmissionFile>—
statusחובה
enum: "submitted" | "late" | "returned" | "graded"—
scoreחובה
number | null—
maxScoreחובה
number—
feedbackMdחובה
string | null≥1 chars
gradedByUserIdחובה
string (uuid) | null—
gradedByNameחובה
string | null≥1 chars
gradedAtחובה
string (date-time) | null—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "assignmentId": "c41b0f8d-c41b-741b-81b0-c41b0f8dc41b",
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "submittedAt": "2026-03-02T09:00:00.000Z",
  "textMd": "string",
  "link": "string",
  "files": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "originalName": "string",
      "mimeType": "string",
      "sizeBytes": 0,
      "downloadUrl": "string",
      "downloadUrlExpiresAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "status": "submitted",
  "score": 1,
  "maxScore": 1,
  "feedbackMd": "string",
  "gradedByUserId": "71e16c27-71e1-71e1-8e16-71e16c2771e1",
  "gradedByName": "string",
  "gradedAt": "2026-03-02T09:00:00.000Z",
  "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

DELETE /api/v1/course-enrollments/{id}

Revoke a self-paced course grant. Emits `course_enrollment.dropped`.

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

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

שםמיקוםסוגמגבלות
idחובה
pathstring—
reason
querystring1–500 chars

דוגמה עם curl

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

תשובות

204The course enrollment was dropped.

מסמך ה-OpenAPI של הממשק עדיין לא מגדיר סכמה מטופסת לתשובה הזו — התשובה עדיין JSON תקין, היא פשוט לא מתועדת כאן.

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/courses/{courseId}/assignments

Create an assignment unit: a lesson of kind "assignment" plus its instructions/due-date/scoring, in one transaction.

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

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

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

גוף הבקשה

שםסוגמגבלות
sectionId
string (uuid)—
titleחובה
string1–200 chars
summary
enum: "" | string | null—
availableFrom
string (date-time) | null—
availableAfterDays
integer | null0–365
estimatedMinutes
integer | null1–600
instructionsMd
enum: "" | string | null—
dueAt
string (date-time) | null—
maxScoreחובה
number0–1000
allowLate
booleandefault: false
submissionKindsחובה
array<enum: "text" | "file" | "link">—
audienceGroupIds
array<string (uuid)> | null—

דוגמה

json
{
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "title": "Midterm Exam",
  "summary": "",
  "availableFrom": "2026-03-02T09:00:00.000Z",
  "availableAfterDays": 0,
  "estimatedMinutes": 1,
  "instructionsMd": "",
  "dueAt": "2026-03-02T09:00:00.000Z",
  "maxScore": 0,
  "allowLate": false,
  "submissionKinds": [
    "text"
  ],
  "audienceGroupIds": [
    "1efa96cc-1efa-7efa-8fa9-1efa96cc1efa"
  ]
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/courses/d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4/assignments" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
    "title": "Midterm Exam",
    "summary": "",
    "availableFrom": "2026-03-02T09:00:00.000Z",
    "availableAfterDays": 0,
    "estimatedMinutes": 1,
    "instructionsMd": "",
    "dueAt": "2026-03-02T09:00:00.000Z",
    "maxScore": 0,
    "allowLate": false,
    "submissionKinds": [
      "text"
    ],
    "audienceGroupIds": [
      "1efa96cc-1efa-7efa-8fa9-1efa96cc1efa"
    ]
  }'

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
courseIdחובה
string (uuid)—
sectionIdחובה
string (uuid)—
titleחובה
string≥1 chars
summaryחובה
string | null≥1 chars
contentMdחובה
string | null≥1 chars
kindחובה
enum: "lesson" | "assignment" | "quiz"—
statusחובה
enum: "draft" | "published"—
publishedAtחובה
string (date-time) | null—
availableFromחובה
string (date-time) | null—
availableAfterDaysחובה
integer | null-9007199254740991–9007199254740991
estimatedMinutesחובה
integer | null-9007199254740991–9007199254740991
sortOrderחובה
integer-9007199254740991–9007199254740991
videoחובה
unknown | null—
assignmentחובה
unknown | null—
quizחובה
unknown | null—
audienceחובה
LessonAudience—
reminderModeחובה
enum: "inherit" | "on" | "off"—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "title": "Midterm Exam",
  "summary": "string",
  "contentMd": "string",
  "kind": "lesson",
  "status": "draft",
  "publishedAt": "2026-03-02T09:00:00.000Z",
  "availableFrom": "2026-03-02T09:00:00.000Z",
  "availableAfterDays": -9007199254740991,
  "estimatedMinutes": -9007199254740991,
  "sortOrder": -9007199254740991,
  "video": "value",
  "assignment": "value",
  "quiz": "value",
  "audience": {
    "restricted": true,
    "groups": [
      {
        "id": "37386ae0-3738-7738-8386-37386ae03738",
        "name": "Algebra I"
      }
    ],
    "hidden": true
  },
  "reminderMode": "inherit",
  "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/courses/{courseId}/audience-groups

List the groups a unit of this course may be restricted to (id and name only, cursor-paginated) — for the «لمن هذا الدرس؟» selector; needs `curriculum.write` or `curriculum.quizzes.manage` (whoever may set an audience), not the groups permission.

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

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

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

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/courses/d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4/audience-groups" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "name": "Algebra I"
    }
  ],
  "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/courses/{courseId}/curriculum/summary

Authoring dashboard tile: section/lesson/published/video counts for one course.

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

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

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

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/courses/d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4/curriculum/summary" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
courseIdחובה
string (uuid)—
sectionCountחובה
integer0–9007199254740991
lessonCountחובה
integer0–9007199254740991
publishedLessonCountחובה
integer0–9007199254740991
videoLessonCountחובה
integer0–9007199254740991
json
{
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "sectionCount": 0,
  "lessonCount": 0,
  "publishedLessonCount": 0,
  "videoLessonCount": 0
}
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/courses/{courseId}/enrollments

List a course’s self-paced enrollments (cursor-paginated, optional status filter).

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

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

שםמיקוםסוגמגבלות
courseIdחובה
pathstring—
cursor
querystring—
limit
queryinteger1–100 · default: 25
status
queryenum: "pending" | "active" | "completed" | "dropped"—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/courses/d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4/enrollments" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
      "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
      "status": "pending",
      "grantedAt": "2026-03-02T09:00:00.000Z",
      "endedAt": "2026-03-02T09:00:00.000Z",
      "priceMinor": 12000,
      "currency": "ILS",
      "grantedByUserId": "fc4e27b3-fc4e-7c4e-84e2-fc4e27b3fc4e",
      "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/courses/{courseId}/enrollments

Grant a student access to a self-paced course. Idempotent, price snapshotted from the course fee, emits `course_enrollment.created`.

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

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

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

גוף הבקשה

שםסוגמגבלות
studentIdחובה
string (uuid)—
priceMinor
integer0–9007199254740991
currency
enum: "ILS" | "USD" | "EUR"—

דוגמה

json
{
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "priceMinor": 12000,
  "currency": "ILS"
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/courses/d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4/enrollments" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
    "priceMinor": 12000,
    "currency": "ILS"
  }'

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
courseIdחובה
string (uuid)—
studentIdחובה
string (uuid)—
statusחובה
enum: "pending" | "active" | "completed" | "dropped"—
grantedAtחובה
string (date-time)—
endedAtחובה
string (date-time) | null—
priceMinorחובה
integer | null-9007199254740991–9007199254740991
currencyחובה
enum: "ILS" | "USD" | "EUR" | null | null—
grantedByUserIdחובה
string (uuid) | null—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "status": "pending",
  "grantedAt": "2026-03-02T09:00:00.000Z",
  "endedAt": "2026-03-02T09:00:00.000Z",
  "priceMinor": 12000,
  "currency": "ILS",
  "grantedByUserId": "fc4e27b3-fc4e-7c4e-84e2-fc4e27b3fc4e",
  "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/courses/{courseId}/lessons

List a course’s lessons (cursor-paginated, optional section/status filter).

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

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

שםמיקוםסוגמגבלות
courseIdחובה
pathstring—
cursor
querystring—
limit
queryinteger1–100 · default: 25
sectionId
querystring (uuid)—
status
queryenum: "draft" | "published"—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/courses/d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4/lessons" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
      "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
      "title": "Midterm Exam",
      "summary": "string",
      "contentMd": "string",
      "kind": "lesson",
      "status": "draft",
      "publishedAt": "2026-03-02T09:00:00.000Z",
      "availableFrom": "2026-03-02T09:00:00.000Z",
      "availableAfterDays": -9007199254740991,
      "estimatedMinutes": -9007199254740991,
      "sortOrder": -9007199254740991,
      "video": "value",
      "assignment": "value",
      "quiz": "value",
      "audience": {
        "restricted": true,
        "groups": [
          {
            "id": "37386ae0-3738-7738-8386-37386ae03738",
            "name": "Algebra I"
          }
        ],
        "hidden": true
      },
      "reminderMode": "inherit",
      "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/courses/{courseId}/lessons

Create a lesson. Omit `sectionId` to use/auto-create the course’s default section.

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

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

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

גוף הבקשה

שםסוגמגבלות
sectionId
string (uuid)—
titleחובה
string1–200 chars
summary
enum: "" | string | null—
contentMd
enum: "" | string | null—
availableFrom
string (date-time) | null—
availableAfterDays
integer | null0–365
estimatedMinutes
integer | null1–600
audienceGroupIds
array<string (uuid)> | null—

דוגמה

json
{
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "title": "Midterm Exam",
  "summary": "",
  "contentMd": "",
  "availableFrom": "2026-03-02T09:00:00.000Z",
  "availableAfterDays": 0,
  "estimatedMinutes": 1,
  "audienceGroupIds": [
    "1efa96cc-1efa-7efa-8fa9-1efa96cc1efa"
  ]
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/courses/d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4/lessons" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
    "title": "Midterm Exam",
    "summary": "",
    "contentMd": "",
    "availableFrom": "2026-03-02T09:00:00.000Z",
    "availableAfterDays": 0,
    "estimatedMinutes": 1,
    "audienceGroupIds": [
      "1efa96cc-1efa-7efa-8fa9-1efa96cc1efa"
    ]
  }'

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
courseIdחובה
string (uuid)—
sectionIdחובה
string (uuid)—
titleחובה
string≥1 chars
summaryחובה
string | null≥1 chars
contentMdחובה
string | null≥1 chars
kindחובה
enum: "lesson" | "assignment" | "quiz"—
statusחובה
enum: "draft" | "published"—
publishedAtחובה
string (date-time) | null—
availableFromחובה
string (date-time) | null—
availableAfterDaysחובה
integer | null-9007199254740991–9007199254740991
estimatedMinutesחובה
integer | null-9007199254740991–9007199254740991
sortOrderחובה
integer-9007199254740991–9007199254740991
videoחובה
unknown | null—
assignmentחובה
unknown | null—
quizחובה
unknown | null—
audienceחובה
LessonAudience—
reminderModeחובה
enum: "inherit" | "on" | "off"—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "title": "Midterm Exam",
  "summary": "string",
  "contentMd": "string",
  "kind": "lesson",
  "status": "draft",
  "publishedAt": "2026-03-02T09:00:00.000Z",
  "availableFrom": "2026-03-02T09:00:00.000Z",
  "availableAfterDays": -9007199254740991,
  "estimatedMinutes": -9007199254740991,
  "sortOrder": -9007199254740991,
  "video": "value",
  "assignment": "value",
  "quiz": "value",
  "audience": {
    "restricted": true,
    "groups": [
      {
        "id": "37386ae0-3738-7738-8386-37386ae03738",
        "name": "Algebra I"
      }
    ],
    "hidden": true
  },
  "reminderMode": "inherit",
  "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/courses/{courseId}/progress

Teacher progress matrix: published units × students who may reach the course, cursor-paginated on students (max 100).

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

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

שםמיקוםסוגמגבלות
courseIdחובה
pathstring—
cursor
querystring—
limit
queryinteger1–100 · default: 25
search
querystring1–200 chars

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/courses/d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4/progress" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
courseIdחובה
string (uuid)—
unitsחובה
array<ProgressMatrixUnit>—
studentsחובה
array<ProgressMatrixStudent>—
cellsחובה
object—
nextCursorחובה
string | null—
json
{
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "units": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "title": "Midterm Exam",
      "kind": "lesson",
      "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
      "sectionTitle": "string",
      "sortOrder": -9007199254740991,
      "completedCount": 0
    }
  ],
  "students": [
    {
      "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
      "fullName": "Ada Lovelace",
      "groupIds": [
        "b0a20d96-b0a2-70a2-8a20-b0a20d96b0a2"
      ],
      "source": "course_enrollment",
      "completedCount": 0,
      "percent": 0
    }
  ],
  "cells": {},
  "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/courses/{courseId}/progress/students/{studentId}

One student's unit-by-unit progress for a course, row-scoped like the matrix.

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

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

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

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/courses/d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4/progress/students/a4a70332-a4a7-74a7-8a70-a4a70332a4a7" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
courseIdחובה
string (uuid)—
studentIdחובה
string (uuid)—
fullNameחובה
string≥1 chars
completedCountחובה
integer0–9007199254740991
percentחובה
integer0–100
unitsחובה
array<StudentProgressUnit>—
json
{
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "fullName": "Ada Lovelace",
  "completedCount": 0,
  "percent": 0,
  "units": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "title": "Midterm Exam",
      "kind": "lesson",
      "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
      "sectionTitle": "string",
      "sortOrder": -9007199254740991,
      "status": "not_started",
      "completedAt": "2026-03-02T09:00:00.000Z",
      "lastSeenAt": "2026-03-02T09:00:00.000Z",
      "assignment": "value",
      "quiz": "value"
    }
  ]
}
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/courses/{courseId}/quizzes

Create a quiz unit: a lesson of kind "quiz" plus its settings, in one transaction. No questions yet.

דורש אימותהרשאהcurriculum.quizzes.manage

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

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

גוף הבקשה

שםסוגמגבלות
sectionId
string (uuid)—
titleחובה
string1–200 chars
summary
enum: "" | string | null—
availableFrom
string (date-time) | null—
availableAfterDays
integer | null0–365
estimatedMinutes
integer | null1–600
timeLimitMinutes
integer | null1–600
attemptsAllowed
integer1–20 · default: 1
shuffle
booleandefault: false
showAnswersAfter
enum: "never" | "after_submit" | "after_due"default: "after_submit"
passScore
number | null≤100000
dueAt
string (date-time) | null—
audienceGroupIds
array<string (uuid)> | null—

דוגמה

json
{
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "title": "Midterm Exam",
  "summary": "",
  "availableFrom": "2026-03-02T09:00:00.000Z",
  "availableAfterDays": 0,
  "estimatedMinutes": 1,
  "timeLimitMinutes": 1,
  "attemptsAllowed": 1,
  "shuffle": false,
  "showAnswersAfter": "after_submit",
  "passScore": 1,
  "dueAt": "2026-03-02T09:00:00.000Z",
  "audienceGroupIds": [
    "1efa96cc-1efa-7efa-8fa9-1efa96cc1efa"
  ]
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/courses/d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4/quizzes" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
    "title": "Midterm Exam",
    "summary": "",
    "availableFrom": "2026-03-02T09:00:00.000Z",
    "availableAfterDays": 0,
    "estimatedMinutes": 1,
    "timeLimitMinutes": 1,
    "attemptsAllowed": 1,
    "shuffle": false,
    "showAnswersAfter": "after_submit",
    "passScore": 1,
    "dueAt": "2026-03-02T09:00:00.000Z",
    "audienceGroupIds": [
      "1efa96cc-1efa-7efa-8fa9-1efa96cc1efa"
    ]
  }'

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
courseIdחובה
string (uuid)—
sectionIdחובה
string (uuid)—
titleחובה
string≥1 chars
summaryחובה
string | null≥1 chars
contentMdחובה
string | null≥1 chars
kindחובה
enum: "lesson" | "assignment" | "quiz"—
statusחובה
enum: "draft" | "published"—
publishedAtחובה
string (date-time) | null—
availableFromחובה
string (date-time) | null—
availableAfterDaysחובה
integer | null-9007199254740991–9007199254740991
estimatedMinutesחובה
integer | null-9007199254740991–9007199254740991
sortOrderחובה
integer-9007199254740991–9007199254740991
videoחובה
unknown | null—
assignmentחובה
unknown | null—
quizחובה
unknown | null—
audienceחובה
LessonAudience—
reminderModeחובה
enum: "inherit" | "on" | "off"—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "title": "Midterm Exam",
  "summary": "string",
  "contentMd": "string",
  "kind": "lesson",
  "status": "draft",
  "publishedAt": "2026-03-02T09:00:00.000Z",
  "availableFrom": "2026-03-02T09:00:00.000Z",
  "availableAfterDays": -9007199254740991,
  "estimatedMinutes": -9007199254740991,
  "sortOrder": -9007199254740991,
  "video": "value",
  "assignment": "value",
  "quiz": "value",
  "audience": {
    "restricted": true,
    "groups": [
      {
        "id": "37386ae0-3738-7738-8386-37386ae03738",
        "name": "Algebra I"
      }
    ],
    "hidden": true
  },
  "reminderMode": "inherit",
  "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/courses/{courseId}/sections

List a course’s sections (cursor-paginated, authoring order).

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

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

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

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/courses/d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4/sections" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
      "title": "Midterm Exam",
      "description": "A short, human-readable description.",
      "sortOrder": -9007199254740991,
      "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/courses/{courseId}/sections

Create a section.

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

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

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

גוף הבקשה

שםסוגמגבלות
titleחובה
string1–200 chars
description
string | string—

דוגמה

json
{
  "title": "Midterm Exam",
  "description": "A short, human-readable description."
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/courses/d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4/sections" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "title": "Midterm Exam",
    "description": "A short, human-readable description."
  }'

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
courseIdחובה
string (uuid)—
titleחובה
string≥1 chars
descriptionחובה
string | null≥1 chars
sortOrderחובה
integer-9007199254740991–9007199254740991
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "title": "Midterm Exam",
  "description": "A short, human-readable description.",
  "sortOrder": -9007199254740991,
  "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

PUT /api/v1/courses/{courseId}/sections/order

Reorder every section of a course in one call (whole-list, unpaginated response envelope).

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

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

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

גוף הבקשה

שםסוגמגבלות
sectionIdsחובה
array<string (uuid)>—

דוגמה

json
{
  "sectionIds": [
    "72a7f6d6-72a7-72a7-8a7f-72a7f6d672a7"
  ]
}

דוגמה עם curl

curl
curl -X PUT "https://your-institute.example/api/v1/courses/d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4/sections/order" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "sectionIds": [
      "72a7f6d6-72a7-72a7-8a7f-72a7f6d672a7"
    ]
  }'

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
      "title": "Midterm Exam",
      "description": "A short, human-readable description.",
      "sortOrder": -9007199254740991,
      "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

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/curriculum/usage

This tenant’s plan usage for the curriculum feature (quota meter).

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

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
videoCoursesחובה
object—
lessonsPerCourseחובה
object—
json
{
  "videoCourses": {
    "used": 0,
    "limit": -1
  },
  "lessonsPerCourse": {
    "limit": -1
  }
}
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? } }`. כל הקודים מפורטים במדריך המוסכמות.

DELETE /api/v1/lesson-files/{id}

Delete a lesson file: removes the row, then the stored object. Audited.

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

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

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

דוגמה עם curl

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

תשובות

204The file was deleted.

מסמך ה-OpenAPI של הממשק עדיין לא מגדיר סכמה מטופסת לתשובה הזו — התשובה עדיין JSON תקין, היא פשוט לא מתועדת כאן.

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/lesson-files/{id}

Rename a lesson file (it keeps its extension), change its description or who may see it.

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

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

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

גוף הבקשה

שםסוגמגבלות
originalName
string1–255 chars
description
enum: "" | string | null—
visibility
enum: "learners" | "staff"—

דוגמה

json
{
  "originalName": "string",
  "description": "",
  "visibility": "learners"
}

דוגמה עם curl

curl
curl -X PATCH "https://your-institute.example/api/v1/lesson-files/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "originalName": "string",
    "description": "",
    "visibility": "learners"
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
lessonIdחובה
string (uuid)—
originalNameחובה
string≥1 chars
mimeTypeחובה
string≥1 chars
sizeBytesחובה
integer0–9007199254740991
descriptionחובה
string | null≥1 chars
visibilityחובה
enum: "learners" | "staff"—
sortOrderחובה
integer-9007199254740991–9007199254740991
createdAtחובה
string (date-time)—
downloadUrlחובה
string—
downloadUrlExpiresAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "originalName": "string",
  "mimeType": "string",
  "sizeBytes": 0,
  "description": "A short, human-readable description.",
  "visibility": "learners",
  "sortOrder": -9007199254740991,
  "createdAt": "2026-03-02T09:00:00.000Z",
  "downloadUrl": "string",
  "downloadUrlExpiresAt": "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

DELETE /api/v1/lessons/{id}

Delete a lesson (cascades its video and progress rows).

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

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

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

דוגמה עם curl

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

תשובות

204The lesson was deleted.

מסמך ה-OpenAPI של הממשק עדיין לא מגדיר סכמה מטופסת לתשובה הזו — התשובה עדיין JSON תקין, היא פשוט לא מתועדת כאן.

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/lessons/{id}

Get one lesson (author view — draft content and video included).

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

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

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

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
courseIdחובה
string (uuid)—
sectionIdחובה
string (uuid)—
titleחובה
string≥1 chars
summaryחובה
string | null≥1 chars
contentMdחובה
string | null≥1 chars
kindחובה
enum: "lesson" | "assignment" | "quiz"—
statusחובה
enum: "draft" | "published"—
publishedAtחובה
string (date-time) | null—
availableFromחובה
string (date-time) | null—
availableAfterDaysחובה
integer | null-9007199254740991–9007199254740991
estimatedMinutesחובה
integer | null-9007199254740991–9007199254740991
sortOrderחובה
integer-9007199254740991–9007199254740991
videoחובה
unknown | null—
assignmentחובה
unknown | null—
quizחובה
unknown | null—
audienceחובה
LessonAudience—
reminderModeחובה
enum: "inherit" | "on" | "off"—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "title": "Midterm Exam",
  "summary": "string",
  "contentMd": "string",
  "kind": "lesson",
  "status": "draft",
  "publishedAt": "2026-03-02T09:00:00.000Z",
  "availableFrom": "2026-03-02T09:00:00.000Z",
  "availableAfterDays": -9007199254740991,
  "estimatedMinutes": -9007199254740991,
  "sortOrder": -9007199254740991,
  "video": "value",
  "assignment": "value",
  "quiz": "value",
  "audience": {
    "restricted": true,
    "groups": [
      {
        "id": "37386ae0-3738-7738-8386-37386ae03738",
        "name": "Algebra I"
      }
    ],
    "hidden": true
  },
  "reminderMode": "inherit",
  "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/lessons/{id}

Update a lesson.

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

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

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

גוף הבקשה

שםסוגמגבלות
sectionId
string (uuid)—
title
string1–200 chars
summary
enum: "" | string | null—
contentMd
enum: "" | string | null—
availableFrom
string (date-time) | null—
availableAfterDays
integer | null0–365
estimatedMinutes
integer | null1–600
audienceGroupIds
array<string (uuid)> | null—
reminderMode
enum: "inherit" | "on" | "off"—

דוגמה

json
{
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "title": "Midterm Exam",
  "summary": "",
  "contentMd": "",
  "availableFrom": "2026-03-02T09:00:00.000Z",
  "availableAfterDays": 0,
  "estimatedMinutes": 1,
  "audienceGroupIds": [
    "1efa96cc-1efa-7efa-8fa9-1efa96cc1efa"
  ],
  "reminderMode": "inherit"
}

דוגמה עם curl

curl
curl -X PATCH "https://your-institute.example/api/v1/lessons/37386ae0-3738-7738-8386-37386ae03738" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
    "title": "Midterm Exam",
    "summary": "",
    "contentMd": "",
    "availableFrom": "2026-03-02T09:00:00.000Z",
    "availableAfterDays": 0,
    "estimatedMinutes": 1,
    "audienceGroupIds": [
      "1efa96cc-1efa-7efa-8fa9-1efa96cc1efa"
    ],
    "reminderMode": "inherit"
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
courseIdחובה
string (uuid)—
sectionIdחובה
string (uuid)—
titleחובה
string≥1 chars
summaryחובה
string | null≥1 chars
contentMdחובה
string | null≥1 chars
kindחובה
enum: "lesson" | "assignment" | "quiz"—
statusחובה
enum: "draft" | "published"—
publishedAtחובה
string (date-time) | null—
availableFromחובה
string (date-time) | null—
availableAfterDaysחובה
integer | null-9007199254740991–9007199254740991
estimatedMinutesחובה
integer | null-9007199254740991–9007199254740991
sortOrderחובה
integer-9007199254740991–9007199254740991
videoחובה
unknown | null—
assignmentחובה
unknown | null—
quizחובה
unknown | null—
audienceחובה
LessonAudience—
reminderModeחובה
enum: "inherit" | "on" | "off"—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "title": "Midterm Exam",
  "summary": "string",
  "contentMd": "string",
  "kind": "lesson",
  "status": "draft",
  "publishedAt": "2026-03-02T09:00:00.000Z",
  "availableFrom": "2026-03-02T09:00:00.000Z",
  "availableAfterDays": -9007199254740991,
  "estimatedMinutes": -9007199254740991,
  "sortOrder": -9007199254740991,
  "video": "value",
  "assignment": "value",
  "quiz": "value",
  "audience": {
    "restricted": true,
    "groups": [
      {
        "id": "37386ae0-3738-7738-8386-37386ae03738",
        "name": "Algebra I"
      }
    ],
    "hidden": true
  },
  "reminderMode": "inherit",
  "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/lessons/{id}/publish

Publish a lesson (emits `lesson.published`). Refused if it has neither content nor a video.

דורש אימותהרשאהcurriculum.publish

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

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

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
courseIdחובה
string (uuid)—
sectionIdחובה
string (uuid)—
titleחובה
string≥1 chars
summaryחובה
string | null≥1 chars
contentMdחובה
string | null≥1 chars
kindחובה
enum: "lesson" | "assignment" | "quiz"—
statusחובה
enum: "draft" | "published"—
publishedAtחובה
string (date-time) | null—
availableFromחובה
string (date-time) | null—
availableAfterDaysחובה
integer | null-9007199254740991–9007199254740991
estimatedMinutesחובה
integer | null-9007199254740991–9007199254740991
sortOrderחובה
integer-9007199254740991–9007199254740991
videoחובה
unknown | null—
assignmentחובה
unknown | null—
quizחובה
unknown | null—
audienceחובה
LessonAudience—
reminderModeחובה
enum: "inherit" | "on" | "off"—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "title": "Midterm Exam",
  "summary": "string",
  "contentMd": "string",
  "kind": "lesson",
  "status": "draft",
  "publishedAt": "2026-03-02T09:00:00.000Z",
  "availableFrom": "2026-03-02T09:00:00.000Z",
  "availableAfterDays": -9007199254740991,
  "estimatedMinutes": -9007199254740991,
  "sortOrder": -9007199254740991,
  "video": "value",
  "assignment": "value",
  "quiz": "value",
  "audience": {
    "restricted": true,
    "groups": [
      {
        "id": "37386ae0-3738-7738-8386-37386ae03738",
        "name": "Algebra I"
      }
    ],
    "hidden": true
  },
  "reminderMode": "inherit",
  "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/lessons/{id}/unpublish

Unpublish a lesson back to draft.

דורש אימותהרשאהcurriculum.publish

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

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

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
courseIdחובה
string (uuid)—
sectionIdחובה
string (uuid)—
titleחובה
string≥1 chars
summaryחובה
string | null≥1 chars
contentMdחובה
string | null≥1 chars
kindחובה
enum: "lesson" | "assignment" | "quiz"—
statusחובה
enum: "draft" | "published"—
publishedAtחובה
string (date-time) | null—
availableFromחובה
string (date-time) | null—
availableAfterDaysחובה
integer | null-9007199254740991–9007199254740991
estimatedMinutesחובה
integer | null-9007199254740991–9007199254740991
sortOrderחובה
integer-9007199254740991–9007199254740991
videoחובה
unknown | null—
assignmentחובה
unknown | null—
quizחובה
unknown | null—
audienceחובה
LessonAudience—
reminderModeחובה
enum: "inherit" | "on" | "off"—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "title": "Midterm Exam",
  "summary": "string",
  "contentMd": "string",
  "kind": "lesson",
  "status": "draft",
  "publishedAt": "2026-03-02T09:00:00.000Z",
  "availableFrom": "2026-03-02T09:00:00.000Z",
  "availableAfterDays": -9007199254740991,
  "estimatedMinutes": -9007199254740991,
  "sortOrder": -9007199254740991,
  "video": "value",
  "assignment": "value",
  "quiz": "value",
  "audience": {
    "restricted": true,
    "groups": [
      {
        "id": "37386ae0-3738-7738-8386-37386ae03738",
        "name": "Algebra I"
      }
    ],
    "hidden": true
  },
  "reminderMode": "inherit",
  "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

DELETE /api/v1/lessons/{id}/video

Remove a lesson’s video (idempotent).

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

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

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

דוגמה עם curl

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

תשובות

204The video was removed (or was already absent).

מסמך ה-OpenAPI של הממשק עדיין לא מגדיר סכמה מטופסת לתשובה הזו — התשובה עדיין JSON תקין, היא פשוט לא מתועדת כאן.

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? } }`. כל הקודים מפורטים במדריך המוסכמות.

PUT /api/v1/lessons/{id}/video

Set (or replace) a lesson’s video source. Only the parsed (provider, externalRef) is ever stored — never the raw URL.

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

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

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

גוף הבקשה

שםסוגמגבלות
urlחובה
string1–2048 chars
title
string1–200 chars
durationSeconds
integer1–86400

דוגמה

json
{
  "url": "https://example.com/webhooks/institflow",
  "title": "Midterm Exam",
  "durationSeconds": 1
}

דוגמה עם curl

curl
curl -X PUT "https://your-institute.example/api/v1/lessons/37386ae0-3738-7738-8386-37386ae03738/video" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "url": "https://example.com/webhooks/institflow",
    "title": "Midterm Exam",
    "durationSeconds": 1
  }'

תשובות

200
שםסוגמגבלות
providerחובה
enum: "youtube"—
externalRefחובה
string≥1 chars
canonicalUrlחובה
string—
embedUrlחובה
string—
titleחובה
string | null≥1 chars
thumbnailUrlחובה
string | null—
durationSecondsחובה
integer | null1–9007199254740991
verifiedAtחובה
string (date-time) | null—
capabilitiesחובה
object—
json
{
  "provider": "youtube",
  "externalRef": "string",
  "canonicalUrl": "string",
  "embedUrl": "string",
  "title": "Midterm Exam",
  "thumbnailUrl": "string",
  "durationSeconds": 1,
  "verifiedAt": "2026-03-02T09:00:00.000Z",
  "capabilities": {
    "progressTracking": true,
    "derivedThumbnail": true,
    "serverMetadata": true,
    "thirdPartyAds": 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? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/lessons/{id}/video/verify

Stamp `verifiedAt` — the author confirms the video actually plays.

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

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

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

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
providerחובה
enum: "youtube"—
externalRefחובה
string≥1 chars
canonicalUrlחובה
string—
embedUrlחובה
string—
titleחובה
string | null≥1 chars
thumbnailUrlחובה
string | null—
durationSecondsחובה
integer | null1–9007199254740991
verifiedAtחובה
string (date-time) | null—
capabilitiesחובה
object—
json
{
  "provider": "youtube",
  "externalRef": "string",
  "canonicalUrl": "string",
  "embedUrl": "string",
  "title": "Midterm Exam",
  "thumbnailUrl": "string",
  "durationSeconds": 1,
  "verifiedAt": "2026-03-02T09:00:00.000Z",
  "capabilities": {
    "progressTracking": true,
    "derivedThumbnail": true,
    "serverMetadata": true,
    "thirdPartyAds": 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/lessons/{lessonId}/files

List a lesson’s files for authors and teachers: every visibility, with a short-lived signed download URL each (whole list, `nextCursor` is always null).

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

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

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

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/lessons/3d477cf4-3d47-7d47-8477-3d477cf43d47/files" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<LessonFile>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
      "originalName": "string",
      "mimeType": "string",
      "sizeBytes": 0,
      "description": "A short, human-readable description.",
      "visibility": "learners",
      "sortOrder": -9007199254740991,
      "createdAt": "2026-03-02T09:00:00.000Z",
      "downloadUrl": "string",
      "downloadUrlExpiresAt": "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/lessons/{lessonId}/files

Register an uploaded lesson file. The stored object’s first bytes are checked against its type; a mismatch deletes the object and refuses the file.

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

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

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

גוף הבקשה

שםסוגמגבלות
originalNameחובה
string1–255 chars
mimeTypeחובה
string1–127 chars
sizeBytesחובה
integer1–20971520
fileId
string (uuid)—
storageKeyחובה
string1–1024 chars
sha256חובה
string—
description
string | string—
visibility
enum: "learners" | "staff"—

דוגמה

json
{
  "originalName": "string",
  "mimeType": "string",
  "sizeBytes": 1,
  "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
  "storageKey": "string",
  "sha256": "string",
  "description": "A short, human-readable description.",
  "visibility": "learners"
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/lessons/3d477cf4-3d47-7d47-8477-3d477cf43d47/files" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "originalName": "string",
    "mimeType": "string",
    "sizeBytes": 1,
    "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
    "storageKey": "string",
    "sha256": "string",
    "description": "A short, human-readable description.",
    "visibility": "learners"
  }'

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
lessonIdחובה
string (uuid)—
originalNameחובה
string≥1 chars
mimeTypeחובה
string≥1 chars
sizeBytesחובה
integer0–9007199254740991
descriptionחובה
string | null≥1 chars
visibilityחובה
enum: "learners" | "staff"—
sortOrderחובה
integer-9007199254740991–9007199254740991
createdAtחובה
string (date-time)—
downloadUrlחובה
string—
downloadUrlExpiresAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "originalName": "string",
  "mimeType": "string",
  "sizeBytes": 0,
  "description": "A short, human-readable description.",
  "visibility": "learners",
  "sortOrder": -9007199254740991,
  "createdAt": "2026-03-02T09:00:00.000Z",
  "downloadUrl": "string",
  "downloadUrlExpiresAt": "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

PUT /api/v1/lessons/{lessonId}/files/order

Reorder every file of a lesson in one call (whole list, `nextCursor` is always null).

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

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

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

גוף הבקשה

שםסוגמגבלות
fileIdsחובה
array<string (uuid)>—

דוגמה

json
{
  "fileIds": [
    "e3c52b67-e3c5-73c5-8c52-e3c52b67e3c5"
  ]
}

דוגמה עם curl

curl
curl -X PUT "https://your-institute.example/api/v1/lessons/3d477cf4-3d47-7d47-8477-3d477cf43d47/files/order" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "fileIds": [
      "e3c52b67-e3c5-73c5-8c52-e3c52b67e3c5"
    ]
  }'

תשובות

200
שםסוגמגבלות
dataחובה
array<LessonFile>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
      "originalName": "string",
      "mimeType": "string",
      "sizeBytes": 0,
      "description": "A short, human-readable description.",
      "visibility": "learners",
      "sortOrder": -9007199254740991,
      "createdAt": "2026-03-02T09:00:00.000Z",
      "downloadUrl": "string",
      "downloadUrlExpiresAt": "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

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/lessons/{lessonId}/files/upload-url

Get a signed URL to upload a lesson file (PUT the object to `uploadUrl` with the same `Content-Type`). Refused up front for a type that is not allowed, a file over 20 MiB, or when the server has no space left (`STORAGE_FULL`).

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

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

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

גוף הבקשה

שםסוגמגבלות
originalNameחובה
string1–255 chars
mimeTypeחובה
string1–127 chars
sizeBytesחובה
integer1–20971520

דוגמה

json
{
  "originalName": "string",
  "mimeType": "string",
  "sizeBytes": 1
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/lessons/3d477cf4-3d47-7d47-8477-3d477cf43d47/files/upload-url" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "originalName": "string",
    "mimeType": "string",
    "sizeBytes": 1
  }'

תשובות

201
שםסוגמגבלות
storageKeyחובה
string—
uploadUrlחובה
string—
expiresAtחובה
string (date-time)—
json
{
  "storageKey": "string",
  "uploadUrl": "string",
  "expiresAt": "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

DELETE /api/v1/lessons/{lessonId}/task

Remove the task under a video lesson. A task that has submissions is refused with 409 (carrying the counts) until `confirmDeleteSubmissions=true` is sent; graded work is never deleted silently.

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

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

שםמיקוםסוגמגבלות
lessonIdחובה
pathstring—
confirmDeleteSubmissions
queryenum: "true" | "false"—

דוגמה עם curl

curl
curl -X DELETE "https://your-institute.example/api/v1/lessons/3d477cf4-3d47-7d47-8477-3d477cf43d47/task" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

204The task was removed.

מסמך ה-OpenAPI של הממשק עדיין לא מגדיר סכמה מטופסת לתשובה הזו — התשובה עדיין JSON תקין, היא פשוט לא מתועדת כאן.

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? } }`. כל הקודים מפורטים במדריך המוסכמות.

PUT /api/v1/lessons/{lessonId}/task

Create or replace the task under a video lesson (instructions, due date, max score, accepted submission kinds). Refused for assignment and quiz units.

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

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

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

גוף הבקשה

שםסוגמגבלות
instructionsMdחובה
string1–20000 chars
dueAt
string (date-time) | null—
maxScoreחובה
number0–1000
allowLate
booleandefault: false
submissionKindsחובה
array<enum: "text" | "file" | "link">—

דוגמה

json
{
  "instructionsMd": "string",
  "dueAt": "2026-03-02T09:00:00.000Z",
  "maxScore": 0,
  "allowLate": false,
  "submissionKinds": [
    "text"
  ]
}

דוגמה עם curl

curl
curl -X PUT "https://your-institute.example/api/v1/lessons/3d477cf4-3d47-7d47-8477-3d477cf43d47/task" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "instructionsMd": "string",
    "dueAt": "2026-03-02T09:00:00.000Z",
    "maxScore": 0,
    "allowLate": false,
    "submissionKinds": [
      "text"
    ]
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
courseIdחובה
string (uuid)—
sectionIdחובה
string (uuid)—
titleחובה
string≥1 chars
summaryחובה
string | null≥1 chars
contentMdחובה
string | null≥1 chars
kindחובה
enum: "lesson" | "assignment" | "quiz"—
statusחובה
enum: "draft" | "published"—
publishedAtחובה
string (date-time) | null—
availableFromחובה
string (date-time) | null—
availableAfterDaysחובה
integer | null-9007199254740991–9007199254740991
estimatedMinutesחובה
integer | null-9007199254740991–9007199254740991
sortOrderחובה
integer-9007199254740991–9007199254740991
videoחובה
unknown | null—
assignmentחובה
unknown | null—
quizחובה
unknown | null—
audienceחובה
LessonAudience—
reminderModeחובה
enum: "inherit" | "on" | "off"—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "title": "Midterm Exam",
  "summary": "string",
  "contentMd": "string",
  "kind": "lesson",
  "status": "draft",
  "publishedAt": "2026-03-02T09:00:00.000Z",
  "availableFrom": "2026-03-02T09:00:00.000Z",
  "availableAfterDays": -9007199254740991,
  "estimatedMinutes": -9007199254740991,
  "sortOrder": -9007199254740991,
  "video": "value",
  "assignment": "value",
  "quiz": "value",
  "audience": {
    "restricted": true,
    "groups": [
      {
        "id": "37386ae0-3738-7738-8386-37386ae03738",
        "name": "Algebra I"
      }
    ],
    "hidden": true
  },
  "reminderMode": "inherit",
  "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/me/courses

Own courses with progress (student), or a linked child’s via `?studentId` (guardian). Published, unlocked lessons only.

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

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

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

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
dataחובה
array<MyCourseResponse>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
      "name": "Algebra I",
      "deliveryMode": "group",
      "lessonCount": 0,
      "completedCount": 0,
      "progressPercent": 0,
      "lastLesson": "value",
      "coverThumbnailUrl": "string"
    }
  ],
  "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/me/courses/{courseId}/lessons

Published lessons of one accessible course, in presentation order. A locked lesson is listed but its body, video and attachments are withheld.

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

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

שםמיקוםסוגמגבלות
courseIdחובה
pathstring—
cursor
querystring—
limit
queryinteger1–100 · default: 25
studentId
querystring (uuid)—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/me/courses/d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4/lessons" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<MyLessonListItem>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
      "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
      "sectionTitle": "string",
      "title": "Midterm Exam",
      "summary": "string",
      "kind": "lesson",
      "estimatedMinutes": -9007199254740991,
      "hasVideo": true,
      "locked": true,
      "availableAt": "2026-03-02T09:00:00.000Z",
      "progress": "value"
    }
  ],
  "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/me/lessons/{lessonId}

One published, accessible lesson: body, video embed, attachments and its neighbours.

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

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

שםמיקוםסוגמגבלות
lessonIdחובה
pathstring—
studentId
querystring (uuid)—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/me/lessons/3d477cf4-3d47-7d47-8477-3d477cf43d47" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
courseIdחובה
string (uuid)—
sectionIdחובה
string (uuid)—
sectionTitleחובה
string≥1 chars
titleחובה
string≥1 chars
summaryחובה
string | null≥1 chars
kindחובה
enum: "lesson" | "assignment" | "quiz"—
estimatedMinutesחובה
integer | null-9007199254740991–9007199254740991
hasVideoחובה
boolean—
lockedחובה
boolean—
availableAtחובה
string (date-time) | null—
progressחובה
unknown | null—
contentMdחובה
string | null≥1 chars
attachmentsחובה
array<MyLessonAttachment>—
videoחובה
unknown | null—
assignmentחובה
unknown | null—
quizחובה
unknown | null—
previousLessonIdחובה
string (uuid) | null—
nextLessonIdחובה
string (uuid) | null—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "sectionTitle": "string",
  "title": "Midterm Exam",
  "summary": "string",
  "kind": "lesson",
  "estimatedMinutes": -9007199254740991,
  "hasVideo": true,
  "locked": true,
  "availableAt": "2026-03-02T09:00:00.000Z",
  "progress": "value",
  "contentMd": "string",
  "attachments": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "originalName": "string",
      "mimeType": "string",
      "sizeBytes": 0,
      "description": "A short, human-readable description.",
      "downloadUrl": "string",
      "downloadUrlExpiresAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "video": "value",
  "assignment": "value",
  "quiz": "value",
  "previousLessonId": "8830a901-8830-7830-830a-8830a9018830",
  "nextLessonId": "289c6ac1-289c-789c-89c6-289c6ac1289c"
}
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? } }`. כל הקודים מפורטים במדריך המוסכמות.

PUT /api/v1/me/lessons/{lessonId}/progress

Record lesson progress (self-reported, non-authoritative). Idempotent: `lesson.completed` is emitted once, on the transition only.

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

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

שםמיקוםסוגמגבלות
lessonIdחובה
pathstring—
studentId
querystring (uuid)—

גוף הבקשה

שםסוגמגבלות
positionSecondsחובה
integer0–86400
watchedSeconds
integer0–86400
completed
boolean—

דוגמה

json
{
  "positionSeconds": 0,
  "watchedSeconds": 0,
  "completed": true
}

דוגמה עם curl

curl
curl -X PUT "https://your-institute.example/api/v1/me/lessons/3d477cf4-3d47-7d47-8477-3d477cf43d47/progress" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "positionSeconds": 0,
    "watchedSeconds": 0,
    "completed": true
  }'

תשובות

200
שםסוגמגבלות
lessonIdחובה
string (uuid)—
studentIdחובה
string (uuid)—
statusחובה
enum: "in_progress" | "completed"—
lastPositionSecondsחובה
integer0–9007199254740991
watchedSecondsחובה
integer0–9007199254740991
firstStartedAtחובה
string (date-time)—
lastSeenAtחובה
string (date-time)—
completedAtחובה
string (date-time) | null—
json
{
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "status": "in_progress",
  "lastPositionSeconds": 0,
  "watchedSeconds": 0,
  "firstStartedAt": "2026-03-02T09:00:00.000Z",
  "lastSeenAt": "2026-03-02T09:00:00.000Z",
  "completedAt": "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/me/lessons/{lessonId}/quiz-attempts

My attempts at this quiz, most recent first, with scores; per-answer detail per `showAnswersAfter`.

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

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

שםמיקוםסוגמגבלות
lessonIdחובה
pathstring—
studentId
querystring (uuid)—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/me/lessons/3d477cf4-3d47-7d47-8477-3d477cf43d47/quiz-attempts" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "quizId": "a5ed7659-a5ed-75ed-8ed7-a5ed7659a5ed",
      "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
      "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
      "attemptNumber": -9007199254740991,
      "status": "in_progress",
      "startedAt": "2026-03-02T09:00:00.000Z",
      "submittedAt": "2026-03-02T09:00:00.000Z",
      "deadlineAt": "2026-03-02T09:00:00.000Z",
      "score": 1,
      "maxScore": 1,
      "passed": true,
      "questions": [
        {
          "id": "37386ae0-3738-7738-8386-37386ae03738",
          "kind": "single",
          "promptMd": "string",
          "options": [
            {
              "id": "37386ae0-3738-7738-8386-37386ae03738",
              "textMd": "string"
            }
          ],
          "points": 0
        }
      ],
      "answers": [
        {
          "questionId": "53cf0780-53cf-73cf-8cf0-53cf078053cf",
          "answer": "string",
          "isCorrect": true,
          "pointsAwarded": 1,
          "needsGrading": true,
          "feedbackMd": "string",
          "correctAnswer": "string"
        }
      ]
    }
  ],
  "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/me/lessons/{lessonId}/quiz-attempts

Start a new attempt (or resume the current in-progress one). Refused when attempts are exhausted or the quiz is closed past its due date. Questions are returned without `correct`, shuffled per attempt when the quiz shuffles.

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

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

שםמיקוםסוגמגבלות
lessonIdחובה
pathstring—
studentId
querystring (uuid)—

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/me/lessons/3d477cf4-3d47-7d47-8477-3d477cf43d47/quiz-attempts" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
quizIdחובה
string (uuid)—
lessonIdחובה
string (uuid)—
studentIdחובה
string (uuid)—
attemptNumberחובה
integer-9007199254740991–9007199254740991
statusחובה
enum: "in_progress" | "submitted" | "expired"—
startedAtחובה
string (date-time)—
submittedAtחובה
string (date-time) | null—
deadlineAtחובה
string (date-time) | null—
scoreחובה
number | null—
maxScoreחובה
number—
passedחובה
boolean | null—
questionsחובה
array<QuizAttemptQuestion>—
answersחובה
array<QuizAttemptAnswer> | null—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "quizId": "a5ed7659-a5ed-75ed-8ed7-a5ed7659a5ed",
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "attemptNumber": -9007199254740991,
  "status": "in_progress",
  "startedAt": "2026-03-02T09:00:00.000Z",
  "submittedAt": "2026-03-02T09:00:00.000Z",
  "deadlineAt": "2026-03-02T09:00:00.000Z",
  "score": 1,
  "maxScore": 1,
  "passed": true,
  "questions": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "kind": "single",
      "promptMd": "string",
      "options": [
        {
          "id": "37386ae0-3738-7738-8386-37386ae03738",
          "textMd": "string"
        }
      ],
      "points": 0
    }
  ],
  "answers": [
    {
      "questionId": "53cf0780-53cf-73cf-8cf0-53cf078053cf",
      "answer": "string",
      "isCorrect": true,
      "pointsAwarded": 1,
      "needsGrading": true,
      "feedbackMd": "string",
      "correctAnswer": "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/me/lessons/{lessonId}/quiz-attempts/{attemptId}

Read one of my attempts.

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

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

שםמיקוםסוגמגבלות
lessonIdחובה
pathstring—
attemptIdחובה
pathstring—
studentId
querystring (uuid)—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/me/lessons/3d477cf4-3d47-7d47-8477-3d477cf43d47/quiz-attempts/ca174553-ca17-7a17-8174-ca174553ca17" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
quizIdחובה
string (uuid)—
lessonIdחובה
string (uuid)—
studentIdחובה
string (uuid)—
attemptNumberחובה
integer-9007199254740991–9007199254740991
statusחובה
enum: "in_progress" | "submitted" | "expired"—
startedAtחובה
string (date-time)—
submittedAtחובה
string (date-time) | null—
deadlineAtחובה
string (date-time) | null—
scoreחובה
number | null—
maxScoreחובה
number—
passedחובה
boolean | null—
questionsחובה
array<QuizAttemptQuestion>—
answersחובה
array<QuizAttemptAnswer> | null—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "quizId": "a5ed7659-a5ed-75ed-8ed7-a5ed7659a5ed",
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "attemptNumber": -9007199254740991,
  "status": "in_progress",
  "startedAt": "2026-03-02T09:00:00.000Z",
  "submittedAt": "2026-03-02T09:00:00.000Z",
  "deadlineAt": "2026-03-02T09:00:00.000Z",
  "score": 1,
  "maxScore": 1,
  "passed": true,
  "questions": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "kind": "single",
      "promptMd": "string",
      "options": [
        {
          "id": "37386ae0-3738-7738-8386-37386ae03738",
          "textMd": "string"
        }
      ],
      "points": 0
    }
  ],
  "answers": [
    {
      "questionId": "53cf0780-53cf-73cf-8cf0-53cf078053cf",
      "answer": "string",
      "isCorrect": true,
      "pointsAwarded": 1,
      "needsGrading": true,
      "feedbackMd": "string",
      "correctAnswer": "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

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? } }`. כל הקודים מפורטים במדריך המוסכמות.

PUT /api/v1/me/lessons/{lessonId}/quiz-attempts/{attemptId}/answers/{questionId}

Upsert one answer. Refused after submit or past the attempt’s deadline.

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

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

שםמיקוםסוגמגבלות
lessonIdחובה
pathstring—
attemptIdחובה
pathstring—
questionIdחובה
pathstring—
studentId
querystring (uuid)—

גוף הבקשה

שםסוגמגבלות
answerחובה
string | array<string> | boolean | null—

דוגמה

json
{
  "answer": "string"
}

דוגמה עם curl

curl
curl -X PUT "https://your-institute.example/api/v1/me/lessons/3d477cf4-3d47-7d47-8477-3d477cf43d47/quiz-attempts/ca174553-ca17-7a17-8174-ca174553ca17/answers/53cf0780-53cf-73cf-8cf0-53cf078053cf" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "answer": "string"
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
quizIdחובה
string (uuid)—
lessonIdחובה
string (uuid)—
studentIdחובה
string (uuid)—
attemptNumberחובה
integer-9007199254740991–9007199254740991
statusחובה
enum: "in_progress" | "submitted" | "expired"—
startedAtחובה
string (date-time)—
submittedAtחובה
string (date-time) | null—
deadlineAtחובה
string (date-time) | null—
scoreחובה
number | null—
maxScoreחובה
number—
passedחובה
boolean | null—
questionsחובה
array<QuizAttemptQuestion>—
answersחובה
array<QuizAttemptAnswer> | null—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "quizId": "a5ed7659-a5ed-75ed-8ed7-a5ed7659a5ed",
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "attemptNumber": -9007199254740991,
  "status": "in_progress",
  "startedAt": "2026-03-02T09:00:00.000Z",
  "submittedAt": "2026-03-02T09:00:00.000Z",
  "deadlineAt": "2026-03-02T09:00:00.000Z",
  "score": 1,
  "maxScore": 1,
  "passed": true,
  "questions": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "kind": "single",
      "promptMd": "string",
      "options": [
        {
          "id": "37386ae0-3738-7738-8386-37386ae03738",
          "textMd": "string"
        }
      ],
      "points": 0
    }
  ],
  "answers": [
    {
      "questionId": "53cf0780-53cf-73cf-8cf0-53cf078053cf",
      "answer": "string",
      "isCorrect": true,
      "pointsAwarded": 1,
      "needsGrading": true,
      "feedbackMd": "string",
      "correctAnswer": "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/me/lessons/{lessonId}/quiz-attempts/{attemptId}/submit

Submit the attempt: auto-grades every closed question, computes score/passed, and stamps lesson_progress completion per §3.6. Refused past the attempt’s deadline.

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

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

שםמיקוםסוגמגבלות
lessonIdחובה
pathstring—
attemptIdחובה
pathstring—
studentId
querystring (uuid)—

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/me/lessons/3d477cf4-3d47-7d47-8477-3d477cf43d47/quiz-attempts/ca174553-ca17-7a17-8174-ca174553ca17/submit" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
quizIdחובה
string (uuid)—
lessonIdחובה
string (uuid)—
studentIdחובה
string (uuid)—
attemptNumberחובה
integer-9007199254740991–9007199254740991
statusחובה
enum: "in_progress" | "submitted" | "expired"—
startedAtחובה
string (date-time)—
submittedAtחובה
string (date-time) | null—
deadlineAtחובה
string (date-time) | null—
scoreחובה
number | null—
maxScoreחובה
number—
passedחובה
boolean | null—
questionsחובה
array<QuizAttemptQuestion>—
answersחובה
array<QuizAttemptAnswer> | null—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "quizId": "a5ed7659-a5ed-75ed-8ed7-a5ed7659a5ed",
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "attemptNumber": -9007199254740991,
  "status": "in_progress",
  "startedAt": "2026-03-02T09:00:00.000Z",
  "submittedAt": "2026-03-02T09:00:00.000Z",
  "deadlineAt": "2026-03-02T09:00:00.000Z",
  "score": 1,
  "maxScore": 1,
  "passed": true,
  "questions": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "kind": "single",
      "promptMd": "string",
      "options": [
        {
          "id": "37386ae0-3738-7738-8386-37386ae03738",
          "textMd": "string"
        }
      ],
      "points": 0
    }
  ],
  "answers": [
    {
      "questionId": "53cf0780-53cf-73cf-8cf0-53cf078053cf",
      "answer": "string",
      "isCorrect": true,
      "pointsAwarded": 1,
      "needsGrading": true,
      "feedbackMd": "string",
      "correctAnswer": "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

PUT /api/v1/me/lessons/{lessonId}/submission

Submit or resubmit an assignment (self-scoped upload for any attached files, `entityType: "assignment_submission"`, `entityId: <lessonId>`, before this call). Refused once graded until the teacher returns it.

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

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

שםמיקוםסוגמגבלות
lessonIdחובה
pathstring—
studentId
querystring (uuid)—

גוף הבקשה

שםסוגמגבלות
textMd
enum: "" | string | null—
link
enum: "" | string | null—

דוגמה

json
{
  "textMd": "",
  "link": ""
}

דוגמה עם curl

curl
curl -X PUT "https://your-institute.example/api/v1/me/lessons/3d477cf4-3d47-7d47-8477-3d477cf43d47/submission" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "textMd": "",
    "link": ""
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
assignmentIdחובה
string (uuid)—
lessonIdחובה
string (uuid)—
studentIdחובה
string (uuid)—
submittedAtחובה
string (date-time)—
textMdחובה
string | null≥1 chars
linkחובה
string | null—
filesחובה
array<SubmissionFile>—
statusחובה
enum: "submitted" | "late" | "returned" | "graded"—
scoreחובה
number | null—
maxScoreחובה
number—
feedbackMdחובה
string | null≥1 chars
gradedByUserIdחובה
string (uuid) | null—
gradedByNameחובה
string | null≥1 chars
gradedAtחובה
string (date-time) | null—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "assignmentId": "c41b0f8d-c41b-741b-81b0-c41b0f8dc41b",
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "submittedAt": "2026-03-02T09:00:00.000Z",
  "textMd": "string",
  "link": "string",
  "files": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "originalName": "string",
      "mimeType": "string",
      "sizeBytes": 0,
      "downloadUrl": "string",
      "downloadUrlExpiresAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "status": "submitted",
  "score": 1,
  "maxScore": 1,
  "feedbackMd": "string",
  "gradedByUserId": "71e16c27-71e1-71e1-8e16-71e16c2771e1",
  "gradedByName": "string",
  "gradedAt": "2026-03-02T09:00:00.000Z",
  "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/me/next-up

What to do next: due assignments (ascending due date, overdue flagged) then unstarted/in-progress units, capped at 10.

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

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

שםמיקוםסוגמגבלות
studentId
querystring (uuid)—

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
studentIdחובה
string (uuid)—
itemsחובה
array<NextUpItem>—
json
{
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "items": [
    {
      "kind": "assignment_due",
      "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
      "courseName": "string",
      "unitId": "6d6cc9ea-6d6c-7d6c-86cc-6d6cc9ea6d6c",
      "unitTitle": "string",
      "unitKind": "lesson",
      "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
      "sectionTitle": "string",
      "dueAt": "2026-03-02T09:00:00.000Z",
      "overdue": 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? } }`. כל הקודים מפורטים במדריך המוסכמות.

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/quizzes/{lessonId}

Update a quiz’s own settings (time limit, attempts allowed, shuffle, show-answers-after, pass score, due date). Lesson-shared fields go through `PATCH /lessons/:id`.

דורש אימותהרשאהcurriculum.quizzes.manage

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

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

גוף הבקשה

שםסוגמגבלות
timeLimitMinutes
integer | null1–600
attemptsAllowed
integer1–20
shuffle
boolean—
showAnswersAfter
enum: "never" | "after_submit" | "after_due"—
passScore
number | null≤100000
dueAt
string (date-time) | null—

דוגמה

json
{
  "timeLimitMinutes": 1,
  "attemptsAllowed": 1,
  "shuffle": true,
  "showAnswersAfter": "never",
  "passScore": 1,
  "dueAt": "2026-03-02T09:00:00.000Z"
}

דוגמה עם curl

curl
curl -X PATCH "https://your-institute.example/api/v1/quizzes/3d477cf4-3d47-7d47-8477-3d477cf43d47" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "timeLimitMinutes": 1,
    "attemptsAllowed": 1,
    "shuffle": true,
    "showAnswersAfter": "never",
    "passScore": 1,
    "dueAt": "2026-03-02T09:00:00.000Z"
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
courseIdחובה
string (uuid)—
sectionIdחובה
string (uuid)—
titleחובה
string≥1 chars
summaryחובה
string | null≥1 chars
contentMdחובה
string | null≥1 chars
kindחובה
enum: "lesson" | "assignment" | "quiz"—
statusחובה
enum: "draft" | "published"—
publishedAtחובה
string (date-time) | null—
availableFromחובה
string (date-time) | null—
availableAfterDaysחובה
integer | null-9007199254740991–9007199254740991
estimatedMinutesחובה
integer | null-9007199254740991–9007199254740991
sortOrderחובה
integer-9007199254740991–9007199254740991
videoחובה
unknown | null—
assignmentחובה
unknown | null—
quizחובה
unknown | null—
audienceחובה
LessonAudience—
reminderModeחובה
enum: "inherit" | "on" | "off"—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
  "title": "Midterm Exam",
  "summary": "string",
  "contentMd": "string",
  "kind": "lesson",
  "status": "draft",
  "publishedAt": "2026-03-02T09:00:00.000Z",
  "availableFrom": "2026-03-02T09:00:00.000Z",
  "availableAfterDays": -9007199254740991,
  "estimatedMinutes": -9007199254740991,
  "sortOrder": -9007199254740991,
  "video": "value",
  "assignment": "value",
  "quiz": "value",
  "audience": {
    "restricted": true,
    "groups": [
      {
        "id": "37386ae0-3738-7738-8386-37386ae03738",
        "name": "Algebra I"
      }
    ],
    "hidden": true
  },
  "reminderMode": "inherit",
  "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/quizzes/{lessonId}/attempts

List a quiz’s attempts (cursor-paginated, optional student/status filters).

דורש אימותהרשאהcurriculum.assignments.grade

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

שםמיקוםסוגמגבלות
lessonIdחובה
pathstring—
cursor
querystring—
limit
queryinteger1–100 · default: 25
studentId
querystring (uuid)—
status
queryenum: "in_progress" | "submitted"—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/quizzes/3d477cf4-3d47-7d47-8477-3d477cf43d47/attempts" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "quizId": "a5ed7659-a5ed-75ed-8ed7-a5ed7659a5ed",
      "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
      "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
      "attemptNumber": -9007199254740991,
      "status": "in_progress",
      "startedAt": "2026-03-02T09:00:00.000Z",
      "submittedAt": "2026-03-02T09:00:00.000Z",
      "deadlineAt": "2026-03-02T09:00:00.000Z",
      "score": 1,
      "maxScore": 1,
      "passed": true,
      "questions": [
        {
          "id": "37386ae0-3738-7738-8386-37386ae03738",
          "kind": "single",
          "promptMd": "string",
          "options": [
            {
              "id": "37386ae0-3738-7738-8386-37386ae03738",
              "textMd": "string"
            }
          ],
          "points": 0
        }
      ],
      "answers": [
        {
          "questionId": "53cf0780-53cf-73cf-8cf0-53cf078053cf",
          "answer": "string",
          "isCorrect": true,
          "pointsAwarded": 1,
          "needsGrading": true,
          "feedbackMd": "string",
          "correctAnswer": "string"
        }
      ]
    }
  ],
  "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/quizzes/{lessonId}/attempts/{attemptId}/answers/{questionId}/grade

Grade a short-answer (`short_text`) answer (points ≤ the question’s own points). Finalises the attempt’s score/passed once nothing is left ungraded. Emits `quiz.graded` on finalisation.

דורש אימותהרשאהcurriculum.assignments.grade

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

שםמיקוםסוגמגבלות
lessonIdחובה
pathstring—
attemptIdחובה
pathstring—
questionIdחובה
pathstring—

גוף הבקשה

שםסוגמגבלות
pointsAwardedחובה
number≥0
feedbackMd
enum: "" | string | null—

דוגמה

json
{
  "pointsAwarded": 0,
  "feedbackMd": ""
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/quizzes/3d477cf4-3d47-7d47-8477-3d477cf43d47/attempts/ca174553-ca17-7a17-8174-ca174553ca17/answers/53cf0780-53cf-73cf-8cf0-53cf078053cf/grade" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "pointsAwarded": 0,
    "feedbackMd": ""
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
quizIdחובה
string (uuid)—
lessonIdחובה
string (uuid)—
studentIdחובה
string (uuid)—
attemptNumberחובה
integer-9007199254740991–9007199254740991
statusחובה
enum: "in_progress" | "submitted" | "expired"—
startedAtחובה
string (date-time)—
submittedAtחובה
string (date-time) | null—
deadlineAtחובה
string (date-time) | null—
scoreחובה
number | null—
maxScoreחובה
number—
passedחובה
boolean | null—
questionsחובה
array<QuizAttemptQuestion>—
answersחובה
array<QuizAttemptAnswer> | null—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "quizId": "a5ed7659-a5ed-75ed-8ed7-a5ed7659a5ed",
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
  "attemptNumber": -9007199254740991,
  "status": "in_progress",
  "startedAt": "2026-03-02T09:00:00.000Z",
  "submittedAt": "2026-03-02T09:00:00.000Z",
  "deadlineAt": "2026-03-02T09:00:00.000Z",
  "score": 1,
  "maxScore": 1,
  "passed": true,
  "questions": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "kind": "single",
      "promptMd": "string",
      "options": [
        {
          "id": "37386ae0-3738-7738-8386-37386ae03738",
          "textMd": "string"
        }
      ],
      "points": 0
    }
  ],
  "answers": [
    {
      "questionId": "53cf0780-53cf-73cf-8cf0-53cf078053cf",
      "answer": "string",
      "isCorrect": true,
      "pointsAwarded": 1,
      "needsGrading": true,
      "feedbackMd": "string",
      "correctAnswer": "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/quizzes/{lessonId}/publish-to-gradebook

Publish each student’s best fully-graded attempt into the gradebook as a `quiz` exam per group — one click, upserts on repeat.

דורש אימותהרשאהcurriculum.assignments.grade

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

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

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/quizzes/3d477cf4-3d47-7d47-8477-3d477cf43d47/publish-to-gradebook" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
publishedחובה
array<object>—
skippedחובה
array<object>—
json
{
  "published": [
    {
      "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
      "groupId": "6dc7fce6-6dc7-7dc7-8c7f-6dc7fce66dc7",
      "examId": "6c140414-6c14-7c14-8140-6c1404146c14",
      "score": 1
    }
  ],
  "skipped": [
    {
      "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
      "reason": "no_group"
    }
  ]
}
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/quizzes/{lessonId}/questions

Add a question to a quiz. Returns the whole quiz (questions included).

דורש אימותהרשאהcurriculum.quizzes.manage

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

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

גוף הבקשה

שםסוגמגבלות
kindחובה
enum: "single" | "multiple" | "true_false" | "short_text"—
promptMdחובה
string1–5000 chars
options
array<object>—
correct
string | array<string> | boolean | null—
pointsחובה
number0–1000

דוגמה

json
{
  "kind": "single",
  "promptMd": "string",
  "options": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "textMd": "string"
    }
  ],
  "correct": "string",
  "points": 0
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/quizzes/3d477cf4-3d47-7d47-8477-3d477cf43d47/questions" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "kind": "single",
    "promptMd": "string",
    "options": [
      {
        "id": "37386ae0-3738-7738-8386-37386ae03738",
        "textMd": "string"
      }
    ],
    "correct": "string",
    "points": 0
  }'

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
lessonIdחובה
string (uuid)—
courseIdחובה
string (uuid)—
timeLimitMinutesחובה
integer | null-9007199254740991–9007199254740991
attemptsAllowedחובה
integer0–9007199254740991
shuffleחובה
boolean—
showAnswersAfterחובה
enum: "never" | "after_submit" | "after_due"—
passScoreחובה
number | null—
dueAtחובה
string (date-time) | null—
publishedAtחובה
string (date-time) | null—
questionsחובה
array<QuizQuestion>—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "timeLimitMinutes": -9007199254740991,
  "attemptsAllowed": 0,
  "shuffle": true,
  "showAnswersAfter": "never",
  "passScore": 1,
  "dueAt": "2026-03-02T09:00:00.000Z",
  "publishedAt": "2026-03-02T09:00:00.000Z",
  "questions": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "quizId": "a5ed7659-a5ed-75ed-8ed7-a5ed7659a5ed",
      "kind": "single",
      "promptMd": "string",
      "options": [
        {
          "id": "37386ae0-3738-7738-8386-37386ae03738",
          "textMd": "string"
        }
      ],
      "correct": "string",
      "points": 0,
      "sortOrder": -9007199254740991,
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

DELETE /api/v1/quizzes/{lessonId}/questions/{questionId}

Delete a question. Returns the whole quiz (questions included).

דורש אימותהרשאהcurriculum.quizzes.manage

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

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

דוגמה עם curl

curl
curl -X DELETE "https://your-institute.example/api/v1/quizzes/3d477cf4-3d47-7d47-8477-3d477cf43d47/questions/53cf0780-53cf-73cf-8cf0-53cf078053cf" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
lessonIdחובה
string (uuid)—
courseIdחובה
string (uuid)—
timeLimitMinutesחובה
integer | null-9007199254740991–9007199254740991
attemptsAllowedחובה
integer0–9007199254740991
shuffleחובה
boolean—
showAnswersAfterחובה
enum: "never" | "after_submit" | "after_due"—
passScoreחובה
number | null—
dueAtחובה
string (date-time) | null—
publishedAtחובה
string (date-time) | null—
questionsחובה
array<QuizQuestion>—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "timeLimitMinutes": -9007199254740991,
  "attemptsAllowed": 0,
  "shuffle": true,
  "showAnswersAfter": "never",
  "passScore": 1,
  "dueAt": "2026-03-02T09:00:00.000Z",
  "publishedAt": "2026-03-02T09:00:00.000Z",
  "questions": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "quizId": "a5ed7659-a5ed-75ed-8ed7-a5ed7659a5ed",
      "kind": "single",
      "promptMd": "string",
      "options": [
        {
          "id": "37386ae0-3738-7738-8386-37386ae03738",
          "textMd": "string"
        }
      ],
      "correct": "string",
      "points": 0,
      "sortOrder": -9007199254740991,
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

PATCH /api/v1/quizzes/{lessonId}/questions/{questionId}

Update a question. Returns the whole quiz (questions included).

דורש אימותהרשאהcurriculum.quizzes.manage

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

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

גוף הבקשה

שםסוגמגבלות
kind
enum: "single" | "multiple" | "true_false" | "short_text"—
promptMd
string1–5000 chars
options
array<object>—
correct
string | array<string> | boolean | null—
points
number0–1000

דוגמה

json
{
  "kind": "single",
  "promptMd": "string",
  "options": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "textMd": "string"
    }
  ],
  "correct": "string",
  "points": 0
}

דוגמה עם curl

curl
curl -X PATCH "https://your-institute.example/api/v1/quizzes/3d477cf4-3d47-7d47-8477-3d477cf43d47/questions/53cf0780-53cf-73cf-8cf0-53cf078053cf" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "kind": "single",
    "promptMd": "string",
    "options": [
      {
        "id": "37386ae0-3738-7738-8386-37386ae03738",
        "textMd": "string"
      }
    ],
    "correct": "string",
    "points": 0
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
lessonIdחובה
string (uuid)—
courseIdחובה
string (uuid)—
timeLimitMinutesחובה
integer | null-9007199254740991–9007199254740991
attemptsAllowedחובה
integer0–9007199254740991
shuffleחובה
boolean—
showAnswersAfterחובה
enum: "never" | "after_submit" | "after_due"—
passScoreחובה
number | null—
dueAtחובה
string (date-time) | null—
publishedAtחובה
string (date-time) | null—
questionsחובה
array<QuizQuestion>—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "timeLimitMinutes": -9007199254740991,
  "attemptsAllowed": 0,
  "shuffle": true,
  "showAnswersAfter": "never",
  "passScore": 1,
  "dueAt": "2026-03-02T09:00:00.000Z",
  "publishedAt": "2026-03-02T09:00:00.000Z",
  "questions": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "quizId": "a5ed7659-a5ed-75ed-8ed7-a5ed7659a5ed",
      "kind": "single",
      "promptMd": "string",
      "options": [
        {
          "id": "37386ae0-3738-7738-8386-37386ae03738",
          "textMd": "string"
        }
      ],
      "correct": "string",
      "points": 0,
      "sortOrder": -9007199254740991,
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

PUT /api/v1/quizzes/{lessonId}/questions/order

Whole-list reorder of a quiz’s questions. Returns the whole quiz (questions included).

דורש אימותהרשאהcurriculum.quizzes.manage

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

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

גוף הבקשה

שםסוגמגבלות
questionIdsחובה
array<string (uuid)>—

דוגמה

json
{
  "questionIds": [
    "e1e98389-e1e9-71e9-8e98-e1e98389e1e9"
  ]
}

דוגמה עם curl

curl
curl -X PUT "https://your-institute.example/api/v1/quizzes/3d477cf4-3d47-7d47-8477-3d477cf43d47/questions/order" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "questionIds": [
      "e1e98389-e1e9-71e9-8e98-e1e98389e1e9"
    ]
  }'

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
lessonIdחובה
string (uuid)—
courseIdחובה
string (uuid)—
timeLimitMinutesחובה
integer | null-9007199254740991–9007199254740991
attemptsAllowedחובה
integer0–9007199254740991
shuffleחובה
boolean—
showAnswersAfterחובה
enum: "never" | "after_submit" | "after_due"—
passScoreחובה
number | null—
dueAtחובה
string (date-time) | null—
publishedAtחובה
string (date-time) | null—
questionsחובה
array<QuizQuestion>—
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "lessonId": "3d477cf4-3d47-7d47-8477-3d477cf43d47",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "timeLimitMinutes": -9007199254740991,
  "attemptsAllowed": 0,
  "shuffle": true,
  "showAnswersAfter": "never",
  "passScore": 1,
  "dueAt": "2026-03-02T09:00:00.000Z",
  "publishedAt": "2026-03-02T09:00:00.000Z",
  "questions": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "quizId": "a5ed7659-a5ed-75ed-8ed7-a5ed7659a5ed",
      "kind": "single",
      "promptMd": "string",
      "options": [
        {
          "id": "37386ae0-3738-7738-8386-37386ae03738",
          "textMd": "string"
        }
      ],
      "correct": "string",
      "points": 0,
      "sortOrder": -9007199254740991,
      "createdAt": "2026-03-02T09:00:00.000Z",
      "updatedAt": "2026-03-02T09:00:00.000Z"
    }
  ],
  "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

DELETE /api/v1/sections/{id}

Delete a section. Fails with 409 if it still has lessons.

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

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

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

דוגמה עם curl

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

תשובות

204The section was deleted.

מסמך ה-OpenAPI של הממשק עדיין לא מגדיר סכמה מטופסת לתשובה הזו — התשובה עדיין JSON תקין, היא פשוט לא מתועדת כאן.

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/sections/{id}

Update a section.

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

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

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

גוף הבקשה

שםסוגמגבלות
title
string1–200 chars
description
enum: "" | string | null—

דוגמה

json
{
  "title": "Midterm Exam",
  "description": ""
}

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
courseIdחובה
string (uuid)—
titleחובה
string≥1 chars
descriptionחובה
string | null≥1 chars
sortOrderחובה
integer-9007199254740991–9007199254740991
createdAtחובה
string (date-time)—
updatedAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
  "title": "Midterm Exam",
  "description": "A short, human-readable description.",
  "sortOrder": -9007199254740991,
  "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

PUT /api/v1/sections/{sectionId}/lessons/order

Reorder every lesson of a section in one call (whole-list, unpaginated response envelope).

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

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

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

גוף הבקשה

שםסוגמגבלות
lessonIdsחובה
array<string (uuid)>—

דוגמה

json
{
  "lessonIds": [
    "fe890885-fe89-7e89-8890-fe890885fe89"
  ]
}

דוגמה עם curl

curl
curl -X PUT "https://your-institute.example/api/v1/sections/c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab/lessons/order" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "lessonIds": [
      "fe890885-fe89-7e89-8890-fe890885fe89"
    ]
  }'

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
      "sectionId": "c1ab4be1-c1ab-71ab-8ab4-c1ab4be1c1ab",
      "title": "Midterm Exam",
      "summary": "string",
      "contentMd": "string",
      "kind": "lesson",
      "status": "draft",
      "publishedAt": "2026-03-02T09:00:00.000Z",
      "availableFrom": "2026-03-02T09:00:00.000Z",
      "availableAfterDays": -9007199254740991,
      "estimatedMinutes": -9007199254740991,
      "sortOrder": -9007199254740991,
      "video": "value",
      "assignment": "value",
      "quiz": "value",
      "audience": {
        "restricted": true,
        "groups": [
          {
            "id": "37386ae0-3738-7738-8386-37386ae03738",
            "name": "Algebra I"
          }
        ],
        "hidden": true
      },
      "reminderMode": "inherit",
      "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

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/students/{studentId}/course-enrollments

List one student’s self-paced course enrollments (cursor-paginated).

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

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

שםמיקוםסוגמגבלות
studentIdחובה
pathstring—
cursor
querystring—
limit
queryinteger1–100 · default: 25
status
queryenum: "pending" | "active" | "completed" | "dropped"—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/students/a4a70332-a4a7-74a7-8a70-a4a70332a4a7/course-enrollments" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "id": "37386ae0-3738-7738-8386-37386ae03738",
      "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
      "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
      "status": "pending",
      "grantedAt": "2026-03-02T09:00:00.000Z",
      "endedAt": "2026-03-02T09:00:00.000Z",
      "priceMinor": 12000,
      "currency": "ILS",
      "grantedByUserId": "fc4e27b3-fc4e-7c4e-84e2-fc4e27b3fc4e",
      "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/students/{studentId}/course-progress

One student’s per-course curriculum progress (cursor-paginated, row-scoped).

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

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

שםמיקוםסוגמגבלות
studentIdחובה
pathstring—
cursor
querystring—
limit
queryinteger1–100 · default: 25
studentId
querystring (uuid)—

דוגמה עם curl

curl
curl -X GET "https://your-institute.example/api/v1/students/a4a70332-a4a7-74a7-8a70-a4a70332a4a7/course-progress" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY"

תשובות

200
שםסוגמגבלות
dataחובה
array<object>—
nextCursorחובה
string | null—
json
{
  "data": [
    {
      "studentId": "a4a70332-a4a7-74a7-8a70-a4a70332a4a7",
      "courseId": "d0e4743a-d0e4-70e4-8e47-d0e4743ad0e4",
      "courseName": "string",
      "lessonCount": 0,
      "completedCount": 0,
      "progressPercent": 0,
      "lastLessonId": "b9705f30-b970-7970-8705-b9705f30b970",
      "lastSeenAt": "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/video-sources/resolve

Parse and (best-effort, YouTube only) enrich a pasted video URL, without saving it anywhere.

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

גוף הבקשה

שםסוגמגבלות
urlחובה
string1–2048 chars

דוגמה

json
{
  "url": "https://example.com/webhooks/institflow"
}

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
providerחובה
enum: "youtube"—
externalRefחובה
string≥1 chars
canonicalUrlחובה
string—
embedUrlחובה
string—
thumbnailUrlחובה
string | null—
titleחובה
string | null≥1 chars
durationSecondsחובה
integer | null1–9007199254740991
capabilitiesחובה
object—
warningsחובה
array<enum: "metadata_unavailable" | "privacy_must_be_unlisted">—
json
{
  "provider": "youtube",
  "externalRef": "string",
  "canonicalUrl": "string",
  "embedUrl": "string",
  "thumbnailUrl": "string",
  "title": "Midterm Exam",
  "durationSeconds": 1,
  "capabilities": {
    "progressTracking": true,
    "derivedThumbnail": true,
    "serverMetadata": true
  },
  "warnings": [
    "metadata_unavailable"
  ]
}
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? } }`. כל הקודים מפורטים במדריך המוסכמות.