files

Files

Signed upload/download URLs for object storage.

5 נקודות קצה

DELETE /api/v1/files/{id}

Delete a file: removes the storage object and the row. Audited.

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

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

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

דוגמה עם curl

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

תשובות

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

GET /api/v1/files/{id}

Get file metadata plus a short-lived (5 min) signed download URL.

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

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

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

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
idחובה
string (uuid)—
kindחובה
enum: "avatar" | "document" | "report" | "attachment"—
originalNameחובה
string—
mimeTypeחובה
string—
sizeBytesחובה
integer-9007199254740991–9007199254740991
sha256חובה
string—
entityTypeחובה
string | null≥1 chars
entityIdחובה
string (uuid) | null—
createdAtחובה
string (date-time)—
downloadUrlחובה
string—
downloadUrlExpiresAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "kind": "avatar",
  "originalName": "string",
  "mimeType": "string",
  "sizeBytes": -9007199254740991,
  "sha256": "string",
  "entityType": "string",
  "entityId": "81693677-8169-7169-8693-816936778169",
  "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

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/files/complete

Finalize an upload after the client has PUT the object to its signed URL.

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

גוף הבקשה

שםסוגמגבלות
fileId
string (uuid)—
storageKeyחובה
string1–1024 chars
sha256חובה
string—
kindחובה
enum: "avatar" | "document" | "report" | "attachment"—
originalNameחובה
string1–255 chars
mimeTypeחובה
enum: "image/jpeg" | "image/png" | "image/webp" | "image/gif" | "application/pdf" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "text/csv"—
sizeBytesחובה
integer1–20971520
entityType
string1–100 chars
entityId
string (uuid)—

דוגמה

json
{
  "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
  "storageKey": "string",
  "sha256": "string",
  "kind": "avatar",
  "originalName": "string",
  "mimeType": "image/jpeg",
  "sizeBytes": 1,
  "entityType": "string",
  "entityId": "81693677-8169-7169-8693-816936778169"
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/files/complete" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "fileId": "0daca32e-0dac-7dac-8aca-0daca32e0dac",
    "storageKey": "string",
    "sha256": "string",
    "kind": "avatar",
    "originalName": "string",
    "mimeType": "image/jpeg",
    "sizeBytes": 1,
    "entityType": "string",
    "entityId": "81693677-8169-7169-8693-816936778169"
  }'

תשובות

201
שםסוגמגבלות
idחובה
string (uuid)—
kindחובה
enum: "avatar" | "document" | "report" | "attachment"—
originalNameחובה
string—
mimeTypeחובה
string—
sizeBytesחובה
integer-9007199254740991–9007199254740991
sha256חובה
string—
entityTypeחובה
string | null≥1 chars
entityIdחובה
string (uuid) | null—
createdAtחובה
string (date-time)—
downloadUrlחובה
string—
downloadUrlExpiresAtחובה
string (date-time)—
json
{
  "id": "37386ae0-3738-7738-8386-37386ae03738",
  "kind": "avatar",
  "originalName": "string",
  "mimeType": "string",
  "sizeBytes": -9007199254740991,
  "sha256": "string",
  "entityType": "string",
  "entityId": "81693677-8169-7169-8693-816936778169",
  "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

POST /api/v1/files/upload-url

Get a signed URL to upload a new file directly to storage (PUT the object to `uploadUrl`).

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

גוף הבקשה

שםסוגמגבלות
kindחובה
enum: "avatar" | "document" | "report" | "attachment"—
originalNameחובה
string1–255 chars
mimeTypeחובה
enum: "image/jpeg" | "image/png" | "image/webp" | "image/gif" | "application/pdf" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "text/csv"—
sizeBytesחובה
integer1–20971520

דוגמה

json
{
  "kind": "avatar",
  "originalName": "string",
  "mimeType": "image/jpeg",
  "sizeBytes": 1
}

דוגמה עם curl

curl
curl -X POST "https://your-institute.example/api/v1/files/upload-url" \
  -H "Authorization: Bearer $INSTITFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "kind": "avatar",
    "originalName": "string",
    "mimeType": "image/jpeg",
    "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? } }`. כל הקודים מפורטים במדריך המוסכמות.

GET /api/v1/storage/usage

This institute’s used storage and, when the server can tell, how much room it still allows (the storage meter).

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

דוגמה עם curl

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

תשובות

200
שםסוגמגבלות
usedBytesחובה
integer0–9007199254740991
limitBytesחובה
integer | null0–9007199254740991
remainingBytesחובה
integer | null0–9007199254740991
serverTotalBytesחובה
integer | null0–9007199254740991
serverAvailableBytesחובה
integer | null0–9007199254740991
reserveBytesחובה
integer | null0–9007199254740991
capEnabledחובה
boolean—
json
{
  "usedBytes": 0,
  "limitBytes": 0,
  "remainingBytes": 0,
  "serverTotalBytes": 0,
  "serverAvailableBytes": 0,
  "reserveBytes": 0,
  "capEnabled": 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? } }`. כל הקודים מפורטים במדריך המוסכמות.