# HTTP API

Система предоставляет versioned JSON API документов для серверных интеграций.
Через него можно получить документ по ID или alias, создать новый и обновить
существующий. Запись проходит через те же поля, валидацию, код рубрики, hooks,
ревизии, terms и JSON snapshot, что и панель управления.

## Маршруты v1

| Метод и URL | Scope | Назначение |
| --- | --- | --- |
| `GET /api/v1/documents/{id}` | `documents:read` | Получить документ по ID. |
| `GET /api/v1/documents/by-alias?alias=...` | `documents:read` | Получить по полному alias. |
| `POST /api/v1/documents` | `documents:write` | Создать документ. |
| `PUT /api/v1/documents/{id}` | `documents:write` | Обновить документ. |
| `PATCH /api/v1/documents/{id}` | `documents:write` | Частично обновить документ. |

## API устанавливаемых модулей

Управляемые модули могут добавлять собственные маршруты и правила доступа. После
установки модуля **Поиск по сайту** доступен публичный endpoint:

| Метод и URL | Доступ | Назначение |
| --- | --- | --- |
| `GET /api/v1/search?q=...` | Публичный, rate limit | Поиск с настраиваемой проекцией полей и форматами `json`, `html`, `both`. |

Состав ответа поиска задаётся в настройках модуля и не связан со scopes API-
токена документов. Полная настройка, параметры и примеры приведены в
[инструкции по поиску](../modules/search.md).

В v1 нет листинга и удаления документов. Не перебирайте ID для выгрузки всего
контента: для такой интеграции нужен отдельный ограниченный endpoint модуля.

## Карта раздела

| Страница | Назначение |
| --- | --- |
| [Токены и безопасность](authentication.md) | Выпуск, scopes, Bearer, срок, отзыв, права и rate limit. |
| [Документы](documents.md) | Формат чтения, полный payload записи, поля и примеры curl. |
| [Ошибки](errors.md) | HTTP-статусы, JSON-контракт и стратегия повтора. |

Все ответы имеют `Content-Type: application/json; charset=UTF-8`. Клиент должен
проверять и HTTP-статус, и `success`, а не искать текст сообщения.