REST API

Templite предоставляет REST API под префиксом /api/cms/. Все эндпоинты документируются через OpenAPI (@OA аннотации в контроллерах) и доступны в Swagger UI.

Аутентификация — Laravel Sanctum. Используется как для админских операций (guard manager), так и для публичных пользователей сайта (guards web, customer, и др.).

Префикс и middleware

/api/cms/...

Глобальный middleware: EnsureFrontendRequestsAreStateful (Sanctum для SPA). Защищённые эндпоинты дополнительно требуют:

auth:sanctum — Bearer-токен или session-cookie.
cms.auth — проверка менеджера.
throttle:cms-api — rate limit (настраивается в RouteServiceProvider).

Часть эндпоинтов имеет дополнительные can:<permission> middleware (can:blocks.code, can:settings.edit, и т.п.).

Аутентификация менеджеров

Логин

POST /api/cms/auth/login

Throttle: 5 запросов в минуту по IP.

Тело:

json

{
    "login": "admin",
    "password": "secret",
    "remember": false
}

Поле — login, не email. Это специфика менеджеров (Manager модель использует логин). Frontend-пользователи логинятся по email — см. ниже.

Успех:

json

{
    "token": "1|abcdef...",
    "user": { "id": 1, "login": "admin", ... }
}

С активной 2FA первый ответ возвращает challenge — нужно дополнительно вызвать /api/cms/auth/two-factor/verify.

Использование токена

Authorization: Bearer 1|abcdef...

Logout, me, profile

POST   /api/cms/auth/logout
GET    /api/cms/auth/me
PUT    /api/cms/auth/profile

Двухфакторная аутентификация (TOTP)

Эндпоинт	Назначение
`POST /api/cms/auth/two-factor/verify`	Подтвердить TOTP-код при логине (throttle 5/min)
`POST /api/cms/auth/two-factor/enable`	Сгенерировать секрет и QR-код для подключения
`POST /api/cms/auth/two-factor/confirm`	Подтвердить включение 2FA вводом первого TOTP
`DELETE /api/cms/auth/two-factor/disable`	Отключить 2FA
`GET /api/cms/auth/two-factor/recovery-codes`	Получить recovery-коды
`POST /api/cms/auth/two-factor/recovery-codes`	Перегенерировать recovery-коды

Аутентификация пользователей сайта

Frontend-пользователи (модель User, таблица cms_users) имеют отдельный auth-flow с параметризованным guard'ом в URL:

POST /api/cms/user-auth/{guard}/login      — throttle 5/min
POST /api/cms/user-auth/{guard}/register   — throttle 3/min
POST /api/cms/user-auth/{guard}/logout
GET  /api/cms/user-auth/{guard}/me

{guard} — имя guard'а из UserType.guard (web, customer, partner, и т.п.).

Профиль пользователя

GET    /api/cms/user-profile/{guard}/
PUT    /api/cms/user-profile/{guard}/
PUT    /api/cms/user-profile/{guard}/password

Middleware: cms.user_auth.

Личные API-токены

Менеджер может выпустить собственные Sanctum-токены (например, для своего скрипта или CI):

GET    /api/cms/tokens         — список своих токенов
POST   /api/cms/tokens         — выпустить новый токен
DELETE /api/cms/tokens/{id}    — отозвать

MCP-токены

Отдельная группа эндпоинтов для управления токенами MCP-сервера:

GET    /api/cms/core-settings/mcp/info               — info без авторизации требований
GET    /api/cms/core-settings/mcp                    — настройки MCP (can:settings.view)
PUT    /api/cms/core-settings/mcp                    — обновить настройки (can:mcp.tokens)
POST   /api/cms/core-settings/mcp/generate-token     — выпустить токен (can:mcp.tokens)
DELETE /api/cms/core-settings/mcp/revoke-token       — отозвать (can:mcp.tokens)

Подробнее — MCP — Установка.

Основные группы эндпоинтов

Все CRUD-операции под auth:sanctum + cms.auth + throttle:cms-api.

Pages

GET    /api/cms/pages
GET    /api/cms/pages/tree
GET    /api/cms/pages/handlers
POST   /api/cms/pages
GET    /api/cms/pages/{id}
PUT    /api/cms/pages/{id}
DELETE /api/cms/pages/{id}
POST   /api/cms/pages/{id}/copy
PUT    /api/cms/pages/reorder
GET    /api/cms/pages/{id}/preview
POST   /api/cms/pages/{id}/screenshot

Page Types

GET    /api/cms/page-types
POST   /api/cms/page-types
GET    /api/cms/page-types/{id}
PUT    /api/cms/page-types/{id}
DELETE /api/cms/page-types/{id}

GET    /api/cms/page-types/{typeId}/attributes
POST   /api/cms/page-types/{typeId}/attributes
PUT    /api/cms/page-type-attributes/{id}
DELETE /api/cms/page-type-attributes/{id}
PUT    /api/cms/page-types/{typeId}/attributes/reorder

GET    /api/cms/pages/{pageId}/attributes
PUT    /api/cms/pages/{pageId}/attributes

Page Blocks

GET    /api/cms/pages/{pageId}/blocks
POST   /api/cms/pages/{pageId}/blocks
GET    /api/cms/page-blocks/{id}
PUT    /api/cms/page-blocks/{id}
DELETE /api/cms/page-blocks/{id}
PUT    /api/cms/pages/{pageId}/blocks/reorder
POST   /api/cms/page-blocks/{id}/copy

PUT    /api/cms/page-blocks/{id}/toggle-cache
POST   /api/cms/page-blocks/{id}/invalidate-cache
GET    /api/cms/page-blocks/{id}/render
PUT    /api/cms/page-blocks/{id}/draft

Page Block Versions

GET    /api/cms/page-blocks/{id}/versions
GET    /api/cms/page-blocks/{id}/versions/{versionId}
PUT    /api/cms/page-blocks/{id}/version/{versionId}        — установить активной
DELETE /api/cms/page-blocks/{id}/versions/{versionId}
DELETE /api/cms/page-blocks/{id}/versions                   — удалить неактивные

Blocks

GET    /api/cms/blocks
POST   /api/cms/blocks
GET    /api/cms/blocks/{id}
PUT    /api/cms/blocks/{id}
DELETE /api/cms/blocks/{id}
POST   /api/cms/blocks/{id}/copy
GET    /api/cms/blocks/{id}/preview
POST   /api/cms/blocks/{id}/screenshot

GET    /api/cms/blocks/{id}/code                              — template/style/script
PUT    /api/cms/blocks/{id}/code     (can:blocks.code, 10/min)

Связанные: Block Presets, Block Types, Block Fields, Block Tabs & Sections, Block Actions — каждая со своими CRUD-эндпоинтами.

Actions

GET    /api/cms/actions
GET    /api/cms/actions/{id}
POST   /api/cms/actions                  (can:actions.code, 10/min)
PUT    /api/cms/actions/{id}             (can:actions.code, 10/min)
DELETE /api/cms/actions/{id}             (can:actions.code, 10/min)
POST   /api/cms/actions/{id}/test        (can:actions.code, 10/min)

Components / Templates / Libraries

Полный CRUD под /api/cms/components, /api/cms/templates, /api/cms/libraries + специальные эндпоинты для кода (/code), полей (/fields, /tabs, /sections), upload библиотек.

Global Settings

GET    /api/cms/settings                                — значения всех полей
PUT    /api/cms/settings                                — массовое обновление значений

GET    /api/cms/settings/pages
POST   /api/cms/settings/pages
PUT    /api/cms/settings/pages/{id}
DELETE /api/cms/settings/pages/{id}
PUT    /api/cms/settings/pages/reorder

POST   /api/cms/settings/sections
PUT    /api/cms/settings/sections/{id}
DELETE /api/cms/settings/sections/{id}
PUT    /api/cms/settings/sections/reorder

POST   /api/cms/settings/fields
PUT    /api/cms/settings/fields/{id}
DELETE /api/cms/settings/fields/{id}
PUT    /api/cms/settings/fields/reorder

GET    /api/cms/settings/preview-wrapper
PUT    /api/cms/settings/preview-wrapper
DELETE /api/cms/settings/preview-wrapper

Media

GET    /api/cms/media
POST   /api/cms/media/upload                   — throttle 10/min, cms.optimize_images
GET    /api/cms/media/serve/{id}               — проксированная отдача файла
POST   /api/cms/media/move
POST   /api/cms/media/delete-many
POST   /api/cms/media/{id}/reprocess
POST   /api/cms/media/{id}/sizes               — добавить размер
DELETE /api/cms/media/{id}/sizes/{sizeName}
GET    /api/cms/media/{id}
PUT    /api/cms/media/{id}
DELETE /api/cms/media/{id}

GET    /api/cms/media/folders
POST   /api/cms/media/folders
PUT    /api/cms/media/folders/{id}
DELETE /api/cms/media/folders/{id}

Managers и Manager Types

GET    /api/cms/managers                                       (can:managers.view)
GET    /api/cms/managers/{id}                                  (can:managers.view)
POST   /api/cms/managers                                       (can:managers.create)
PUT    /api/cms/managers/{id}                                  (can:managers.edit)
DELETE /api/cms/managers/{id}                                  (can:managers.delete)

GET    /api/cms/managers/{id}/sessions                         (can:managers.view)
DELETE /api/cms/managers/{id}/sessions                         (can:managers.edit)
DELETE /api/cms/managers/{id}/sessions/{sessionId}             (can:managers.edit)
DELETE /api/cms/managers/{id}/two-factor                       (can:managers.edit)

GET    /api/cms/manager-types                                  (can:managers.view)
POST   /api/cms/manager-types                                  (can:managers.edit)
PUT    /api/cms/manager-types/{id}                             (can:managers.edit)
DELETE /api/cms/manager-types/{id}                             (can:managers.edit)

GET    /api/cms/guards
GET    /api/cms/guards/{guard}/permissions

Frontend Users

GET    /api/cms/user-types
POST   /api/cms/user-types
GET    /api/cms/user-types/{id}
PUT    /api/cms/user-types/{id}
DELETE /api/cms/user-types/{id}

GET    /api/cms/user-types/{typeId}/fields
POST   /api/cms/user-types/{typeId}/fields
PUT    /api/cms/user-fields/{id}
DELETE /api/cms/user-fields/{id}

GET    /api/cms/users
POST   /api/cms/users
GET    /api/cms/users/{id}
PUT    /api/cms/users/{id}
DELETE /api/cms/users/{id}
PUT    /api/cms/users/{id}/toggle-active

Cities и Languages

GET    /api/cms/cities
POST   /api/cms/cities
POST   /api/cms/cities/import
PUT    /api/cms/cities/reorder
... CRUD по id

GET    /api/cms/languages
POST   /api/cms/languages
PUT    /api/cms/languages/reorder
PUT    /api/cms/languages/{id}/set-default
... CRUD по id

City Pages

GET    /api/cms/pages/{pageId}/cities
GET    /api/cms/pages/{pageId}/cities/{cityId}
PUT    /api/cms/pages/{pageId}/cities/{cityId}
PUT    /api/cms/city-pages/{cityPageId}/blocks
POST   /api/cms/pages/{pageId}/cities/{cityId}/materialize
POST   /api/cms/pages/{pageId}/cities/{cityId}/dematerialize

Translations

GET    /api/cms/pages/{page}/translations/{lang}
PUT    /api/cms/pages/{page}/translations/{lang}
GET    /api/cms/pages/{page}/block-translations/{lang}
PUT    /api/cms/pages/{page}/block-translations/{lang}
GET    /api/cms/page-blocks/{pageBlock}/translations/{lang}
PUT    /api/cms/page-blocks/{pageBlock}/translations/{lang}
POST   /api/cms/page-blocks/{pageBlock}/translations/{lang}/copy-from-default
GET    /api/cms/global-settings/translations/{lang}
PUT    /api/cms/global-settings/translations/{lang}

Core Settings, Queues, Schedule

GET    /api/cms/core-settings                          (can:settings.view)
PUT    /api/cms/core-settings                          (can:settings.edit)

GET    /api/cms/core-settings/queues/stats             (can:settings.view)
GET    /api/cms/core-settings/queues/failed            (can:settings.view)
POST   /api/cms/core-settings/queues/restart           (can:settings.edit, 10/min)
POST   /api/cms/core-settings/queues/pause             (can:settings.edit, 10/min)
POST   /api/cms/core-settings/queues/resume            (can:settings.edit, 10/min)
POST   /api/cms/core-settings/queues/failed/retry-all  (can:settings.edit, 10/min)
POST   /api/cms/core-settings/queues/failed/flush      (can:settings.edit, 10/min)

GET    /api/cms/core-settings/schedule/tasks
GET    /api/cms/core-settings/schedule/history
POST   /api/cms/core-settings/schedule/tasks/{command}/run
POST   /api/cms/core-settings/schedule/tasks
PUT    /api/cms/core-settings/schedule/tasks/{id}
DELETE /api/cms/core-settings/schedule/tasks/{id}

File Manager (публичные файлы)

GET    /api/cms/file-manager                          (can:files.manage)
GET    /api/cms/file-manager/file
PUT    /api/cms/file-manager/file
POST   /api/cms/file-manager/upload                   (throttle 10/min)
POST   /api/cms/file-manager/folder
POST   /api/cms/file-manager/create-file
POST   /api/cms/file-manager/delete
PATCH  /api/cms/file-manager/rename
PATCH  /api/cms/file-manager/move
GET    /api/cms/file-manager/download

Export / Import

GET    /api/cms/export/entities
POST   /api/cms/export/preview               (throttle 10/min)
POST   /api/cms/export/run                   (throttle 10/min)
POST   /api/cms/import/upload                (throttle 10/min)
POST   /api/cms/import/run                   (throttle 10/min)
GET    /api/cms/export-import/log
GET    /api/cms/export-import/log/{id}/download

Cache & Assets

POST   /api/cms/cache/clear                  (throttle 10/min)
POST   /api/cms/assets/compile/{pageId}      (throttle 10/min)
POST   /api/cms/assets/compile-all           (throttle 10/min)
POST   /api/cms/assets/rebuild               (throttle 10/min)

Logs

GET    /api/cms/logs

Swagger UI

Все эндпоинты задокументированы через OpenAPI (аннотации @OA в контроллерах). Доступ к Swagger UI — https://your-domain.com/api/documentation (через L5-Swagger).

Генерация документации:

bash

docker exec templite-app php artisan l5-swagger:generate

TIP

В production генерировать спецификацию каждый раз не нужно. Установите L5_SWAGGER_GENERATE_ALWAYS=false в .env после первой генерации. Saved JSON живёт в storage/api-docs/api-docs.json.

Default-аватары

CMS поставляет 30 предустановленных аватарок (для пользователей без загруженного фото):

GET /api/cms/avatars/{number}    — number от 1 до 30

Доступ без авторизации, отдаётся с Cache-Control: public, max-age=31536000, immutable.

Rate limits

Тип	Лимит	Где применяется
Login (admin)	5/min	`/api/cms/auth/login`, `/api/cms/auth/two-factor/verify`
Login (frontend)	5/min	`/api/cms/user-auth/{guard}/login`
Register	3/min	`/api/cms/user-auth/{guard}/register`
Code editing	10/min	`/blocks/{id}/code`, `/components/{id}/code`, `/templates/{id}/code`, `/actions/*`
Heavy ops	10/min	upload, compile, clear cache, export/import
Общий API	`cms-api` throttle	Все защищённые эндпоинты (настраивается в `RouteServiceProvider`)

Можно ужесточить через THROTTLE_* env-переменные.

CORS

Для CORS-запросов из других доменов:

dotenv

SANCTUM_STATEFUL_DOMAINS=admin.example.com,app.example.com

Дополнительные CORS-настройки — стандартный config/cors.php Laravel.

MCP и API

MCP-сервер использует те же REST-эндпоинты под капотом. MCP-tools мапятся на конкретные API-вызовы:

list_pages → GET /api/cms/pages
create_block → POST /api/cms/blocks
update_settings → PUT /api/cms/settings
и так далее.

Это значит: добавление нового API-эндпоинта автоматически расширяет возможности AI-агентов через MCP. См. MCP — Tools.

Подводные камни

Префикс — /api/cms/, не /api/. Все запросы к CMS API идут через этот префикс.
Логин менеджера принимает login, не email. У Manager модели есть колонка login. Frontend-пользователи (User) логинятся по email через /api/cms/user-auth/{guard}/login.
Sanctum stateful domains. Без корректного SANCTUM_STATEFUL_DOMAINS в .env Vue-острова админки и SPA-клиенты получат 401 / CSRF mismatch.
2FA-flow двухшаговый. Первый /auth/login возвращает challenge при включённой 2FA, нужен дополнительный /auth/two-factor/verify с кодом.
Permissions проверяются через can: middleware. Запрещённые операции возвращают 403 — это нормально, проверяйте права менеджера.
Throttle разный для разных эндпоинтов. Login и code-editing жёстче (5-10/min), остальное на общем cms-api throttle.
Swagger UI в production — security risk. Раскрывает структуру эндпоинтов. После первой генерации L5_SWAGGER_GENERATE_ALWAYS=false обязателен. Можно вообще закрыть доступ через middleware.
/api/cms/media/serve/{id} проксирует файл через CMS (для приватных файлов и проверки прав). Прямой URL — Storage::disk($disk)->url($path) или $file->url.
MCP-токены управляются через REST, не через artisan. Используйте POST /api/cms/core-settings/mcp/generate-token либо MCP-конфигурацию в UI.

Связанные разделы

Первый вход в админку — про менеджеров, 2FA в админке
Пользователи — frontend User модель, multi-guard
Artisan и безопасность — security checklist
MCP — Установка — MCP-токены и подключение
MCP — Tools — маппинг tools на API

REST API ​

Префикс и middleware ​

Аутентификация менеджеров ​

Логин ​

Использование токена ​

Logout, me, profile ​

Двухфакторная аутентификация (TOTP) ​

Аутентификация пользователей сайта ​

Профиль пользователя ​

Личные API-токены ​

MCP-токены ​

Основные группы эндпоинтов ​

Pages ​

Page Types ​

Page Blocks ​

Page Block Versions ​

Blocks ​

Actions ​

Components / Templates / Libraries ​

Global Settings ​

Media ​

Managers и Manager Types ​

Frontend Users ​

Cities и Languages ​

City Pages ​

Translations ​

Core Settings, Queues, Schedule ​

File Manager (публичные файлы) ​

Export / Import ​

Cache & Assets ​

Logs ​

Swagger UI ​

Default-аватары ​

Rate limits ​

CORS ​

MCP и API ​

Подводные камни ​

Связанные разделы ​