Документация API домена kastomos.site

Этот раздел описывает публичные и защищённые эндпоинты доменного сервера. Используйте его, чтобы интегрировать внешние сервисы, агенты и автоматические проверки с развернутой инфраструктурой.

Текущее время (UTC): 2026-06-19T11:26:27.575057+00:00.
Версия приложения: 1.0.0.

Интерактивные тесты На главную

Базовые сведения

Основные настройки и соглашения, которые применяются ко всем запросам.

Базовый URL

Все примеры ниже предполагают работу через публичный домен https://kastomos.site. При проверке с другого адреса замените доменное имя на ваш URL.

Формат данных

Сервер принимает и возвращает JSON (UTF-8) для REST-эндпоинтов и использует поток Server-Sent Events для уведомлений о заказах. Для форм отправки заказов поддерживается multipart/form-data с вложением SVG.

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

Защищённые запросы требуют заголовок Authorization: Bearer <token>. Получите готовые токены на странице /tests или программно через /api/tokens.

Публичные эндпоинты

Доступны без аутентификации и подходят для мониторинга состояния сервера.

GET /health

Простая проверка готовности сервиса. Возвращает статус ok.

{
  "status": "ok"
}
GET /api/ping

Возвращает признак доступности API и текущую временную метку в формате ISO 8601. 

{
  "pong": true,
  "ts": "2024-01-30T12:34:56.789Z"
}
GET /api/summary

Возвращает агрегированную сводку: список метрик, проектов и доступных агентов, сформированную на основе сохранённых данных и последних заказов. 

{
  "summary": {
    "updated_at": "2024-01-30T12:00:00Z",
    "highlights": [
      { "label": "Активные проекты", "value": "3" }
    ],
    "projects": [...],
    "agents": [...]
  }
}
GET /api/orders

Возвращает историю последних заказов, включая коды, размеры, точки выдачи и ссылки на SVG-файлы, если они были загружены. 

{
  "orders": [
    {
      "order_code": "QA-123",
      "point_name": "Test Point",
      "svg_url": "/orders/QA-123.svg"
    }
  ]
}
GET /api/orders/stream

Поток Server-Sent Events с обновлениями заказов в реальном времени. После подключения клиент получает полный список текущих заказов и далее события orders при каждом обновлении. Для поддержания соединения сервер отправляет keep-alive каждые 25 секунд. 

event: orders
data: {"orders": [...]} 

: keep-alive

Защищённые эндпоинты

Требуют валидный токен доступа. Используйте их для обновления сводки и регистрации заказов.

POST PUT /api/summary

Обновляет хранимую сводку. Тело запроса — JSON с полями highlights, projects, agents. После сохранения сервер возвращает актуальную сводку. 

{
  "highlights": [
    { "label": "Готовность", "value": "100%", "delta": "+5%" }
  ],
  "projects": [
    { "name": "Website", "status": "в работе", "updated_at": "2024-01-30" }
  ],
  "agents": [
    { "name": "QA Bot", "role": "Тестирование", "skills": ["API", "UI"] }
  ]
}
POST /api/orders

Создаёт или обновляет заказ. Поддерживает форму multipart/form-data с полями order_code (обязательно), order_no, size, point_id, point_name, created_at и файлом svg. При успешной операции вещает обновление во все активные SSE-подписки. 

POST /api/orders HTTP/1.1
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=...

--...
Content-Disposition: form-data; name="order_code"

QA-123
--...
Content-Disposition: form-data; name="svg"; filename="label.svg"
Content-Type: image/svg+xml

<svg>...</svg>
--...--

Управление токенами

Используйте эти эндпоинты, чтобы получить или обновить секреты для тестов и агентов.

GET /api/tokens

Возвращает доступные токены. Если значения заданы в переменных окружения, источник будет указан как config; автоматически сгенерированные секреты помечаются как generated. 

{
  "tokens": {
    "tests": { "token": "...", "updated_at": "2024-01-30T12:00:00Z", "source": "generated" },
    "agents": { "token": "...", "updated_at": null, "source": "config" }
  }
}
POST /api/tokens/refresh

Генерирует новый токен для указанного типа (tests или agents), если значения не заданы через переменные окружения. Тело запроса: {"type": "tests"}. 

{
  "token": {
    "token": "new-secret",
    "updated_at": "2024-01-30T12:34:56Z",
    "source": "generated"
  }
}