# API Reference — File Portal

Базовый URL: `https://mirror1.caelixflow.com`

## Аутентификация

Запросы с правами записи требуют заголовка:

```
Authorization: Bearer <token>
```

Токен выдаёт админ (в личке или в чате). Живёт сутки, потом новый.

## Endpoints

### `GET /api/v1/files`

Список файлов в директории.

**Параметры:**

| Параметр | Тип | Описание |
|----------|-----|----------|
| `path` | string | Путь относительно корня |
| `recursive` | bool | Рекурсивный обход |
| `limit` | int | Макс. записей (по умолчанию 100) |

**Ответ 200:**

```json
{
  "path": "/docs",
  "items": [
    {
      "name": "platform-overview.md",
      "size": 2048,
      "modified": "2026-06-15T10:30:00Z",
      "mime": "text/markdown"
    }
  ]
}
```

### `POST /api/v1/upload`

Загрузка **нового** файла.

**Тело:** `multipart/form-data`

| Поле | Тип | Обязательно |
|------|-----|-------------|
| `file` | binary | да |
| `path` | string | да |
| `overwrite` | bool | нет |

**Ответ 201:**

```json
{
  "id": "f_8a3b2c1d",
  "url": "https://mirror1.caelixflow.com/docs/platform-overview.md",
  "checksum": "sha256:abc123..."
}
```

### `PUT /api/v1/files/{path}`

Перезапись **существующего** файла по пути. Тело — raw bytes файла.

```bash
curl -X PUT "https://mirror1.caelixflow.com/api/v1/files/docs/notes.md" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/markdown" \
  --data-binary @notes.md
```

**Когда использовать:**
- CaelixSync обновил локальный файл → PUT на сервер
- Meridian заменил картинку, URL тот же
- Правка md «сохранить поверх» без нового имени

**Ответ 200** — файл заменён. **404** — файла ещё нет, сначала POST.

| | POST | PUT |
|--|------|-----|
| Файл существует | дубликат или overwrite-флаг | перезапись |
| Тело | multipart | raw bytes |
| Типичный клиент | браузер, curl -F | синк, CMS, скрипты |

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

Удаление файла. Требует роль `editor` или выше.

### `GET /api/v1/health`

Проверка состояния сервиса.

```json
{
  "status": "ok",
  "version": "2.4.1",
  "uptime_seconds": 864000
}
```

## Коды ошибок

| Код | Значение |
|-----|----------|
| 400 | Некорректный запрос |
| 401 | Не авторизован |
| 403 | Недостаточно прав |
| 404 | Файл не найден |
| 413 | Файл слишком большой |
| 429 | Превышен лимит запросов |

## Rate limits

- Чтение: 300 req/min
- Запись: 60 req/min