Обновление контента

Этот API позволяет внешнему сервису или скрипту заменить содержимое конкретного section без входа в редактор One File Docs.

Что делает API

Механизм удобен, когда контент собирается в CI, приходит из CMS, генерируется отдельным процессом или должен обновляться по событию из другой системы.

API работает только для section типов page и API Reference. Для доступа используется секретный ключ section, который хранится в настройках внешнего обновления.

Как включить

  1. Откройте нужный document в workspace.
  2. Перейдите в section типа page или API Reference.
  3. Откройте блок Внешнее обновление контента.
  4. Включите API и сохраните изменения.
  5. Скопируйте выданный secret key и endpoint.

Функция доступна только на тарифе Pro. Если API выключить, ключ сразу отзывается. Если ключ скомпрометирован, его лучше перевыпустить и обновить интеграцию.

Endpoint и авторизация

Запрос отправляется на серверный endpoint:

POST /api/content-sync/:syncKey

Вместо :syncKey подставляется секретный ключ конкретного section. Отдельного заголовка авторизации у этого метода нет: доступ полностью держится на знании ключа.

По этой причине ключ нужно хранить как секрет, не вставлять в публичный frontend-код и не писать в открытые логи.

Формат запроса

API принимает JSON и ожидает строковое поле content.

{
  "content": "<h1>Updated content</h1><p>Generated externally.</p>"
}

Для section типа page в content передается HTML-строка, которая полностью заменяет текущее содержимое раздела.

Для section типа API Reference в content тоже должна прийти строка, но внутри нее должен лежать валидный extractor JSON. Сервер проверяет его и сохраняет в нормализованном виде.

const endpoint = "https://onefiledocs.com/api/content-sync/SECTION_SECRET";
const html = "<h1>Release notes</h1><p>Synced from CI.</p>";

await fetch(endpoint, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    content: html,
  }),
});

Пример для API Reference отличается только содержимым переменной content: туда нужно передать строку с JSON, а не HTML.

Успешный ответ

При успешной замене контента сервер возвращает 200 OK и JSON со служебной информацией:

{
  "status": "ok",
  "documentId": 12,
  "sectionId": 34,
  "sectionIdentifier": "release-notes",
  "sectionType": "page",
  "updatedAt": "2026-07-01T07:00:00.000Z"
}

sectionIdentifier это slug section внутри документа. updatedAt возвращается в UTC ISO-формате.

Ошибки и ограничения

Если ключ пустой, тело запроса некорректно или content не является строкой, сервер вернет 400 Bad Request.

Если section не поддерживает этот механизм, внешние обновления выключены или у владельца документа больше нет активного Pro, сервер вернет 403 Forbidden.

Если ключ не найден, сервер вернет 404 Not Found.

Для API Reference невалидный extractor JSON тоже приводит к 400 Bad Request.

Каждый вызов полностью заменяет текущее содержимое section. Частичного merge на стороне сервера нет, поэтому интеграция должна отправлять полный актуальный контент.