# Files

Signed upload/download URLs for object storage.

Generated from `apps/api/openapi.json`. HTML version: https://docs.institflow.com/en/reference/files

5 operations.

## DELETE /api/v1/files/{id}

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

- Operation id: `FilesController_remove_v1`
- Permission: `files.write`
- Auth: credential required
- `Idempotency-Key`: required for API-key callers

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Responses

**200** — The file was deleted.

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

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

## GET /api/v1/files/{id}

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

- Operation id: `FilesController_getById_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: not required

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes |  |

### Responses

**200** — Success.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |
| `kind` | enum: "avatar" \| "document" \| "report" \| "attachment" | yes |  |
| `originalName` | string | yes |  |
| `mimeType` | string | yes |  |
| `sizeBytes` | integer | yes | -9007199254740991–9007199254740991 |
| `sha256` | string | yes |  |
| `entityType` | string \| null | yes | ≥1 chars |
| `entityId` | string (uuid) \| null | yes |  |
| `createdAt` | string (date-time) | yes |  |
| `downloadUrl` | string | yes |  |
| `downloadUrlExpiresAt` | string (date-time) | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

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

## POST /api/v1/files/complete

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

- Operation id: `FilesController_complete_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: required for API-key callers

### Request body

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `fileId` | string (uuid) | no |  |
| `storageKey` | string | yes | 1–1024 chars |
| `sha256` | string | yes |  |
| `kind` | enum: "avatar" \| "document" \| "report" \| "attachment" | yes |  |
| `originalName` | string | yes | 1–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" | yes |  |
| `sizeBytes` | integer | yes | 1–20971520 |
| `entityType` | string | no | 1–100 chars |
| `entityId` | string (uuid) | no |  |

```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"
}
```

### Responses

**201** — Success.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes |  |
| `kind` | enum: "avatar" \| "document" \| "report" \| "attachment" | yes |  |
| `originalName` | string | yes |  |
| `mimeType` | string | yes |  |
| `sizeBytes` | integer | yes | -9007199254740991–9007199254740991 |
| `sha256` | string | yes |  |
| `entityType` | string \| null | yes | ≥1 chars |
| `entityId` | string (uuid) \| null | yes |  |
| `createdAt` | string (date-time) | yes |  |
| `downloadUrl` | string | yes |  |
| `downloadUrlExpiresAt` | string (date-time) | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
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"
  }'
```

## POST /api/v1/files/upload-url

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

- Operation id: `FilesController_createUploadUrl_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: required for API-key callers

### Request body

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `kind` | enum: "avatar" \| "document" \| "report" \| "attachment" | yes |  |
| `originalName` | string | yes | 1–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" | yes |  |
| `sizeBytes` | integer | yes | 1–20971520 |

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

### Responses

**201** — Success.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `storageKey` | string | yes |  |
| `uploadUrl` | string | yes |  |
| `expiresAt` | string (date-time) | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

```bash
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
  }'
```

## 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).

- Operation id: `StorageUsageController_usage_v1`
- Permission: —
- Auth: credential required
- `Idempotency-Key`: not required

### Responses

**200** — Success.

| Property | Type | Required | Constraints |
| --- | --- | --- | --- |
| `usedBytes` | integer | yes | 0–9007199254740991 |
| `limitBytes` | integer \| null | yes | 0–9007199254740991 |
| `remainingBytes` | integer \| null | yes | 0–9007199254740991 |
| `serverTotalBytes` | integer \| null | yes | 0–9007199254740991 |
| `serverAvailableBytes` | integer \| null | yes | 0–9007199254740991 |
| `reserveBytes` | integer \| null | yes | 0–9007199254740991 |
| `capEnabled` | boolean | yes |  |

Every other status answers with the shared `ErrorEnvelope` — see
https://docs.institflow.com/md/en/error-codes.md

### Example request

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