API-доступ: удалённая запись заметок

Внешнее приложение может складывать заметки в ваш блокнот автоматически — по секретному ключу, без логина и пароля. Удобно для ботов, скриптов, форм и любых интеграций, которые должны «оставить запись».

Что это и зачем

Вы выдаёте приложению API-ключ — длинную секретную строку. Приложение прикладывает её к каждому запросу, а leavemessage создаёт заметку в привязанном к ключу блокноте. Например:

• телеграм-бот складывает пересланные сообщения в блокнот «Входящее»;
• скрипт по расписанию пишет ежедневный отчёт;
• форма на другом сайте отправляет ответы прямо в ваш блокнот.

Как получить ключ

1. Откройте настройки нужного блокнота (карандаш у блокнота).
2. Раздел «API-доступ» → «Управление ключами».
3. Введите название, отметьте блокноты, к которым ключ имеет доступ (один или несколько), и — по желанию — «только чтение». Нажмите «Создать ключ».
4. Ключ вида lm_live_… покажется один раз — скопируйте его сразу.

Куда пишет ключ и что ему можно

Ключ работает со своим списком блокнотов — одним или несколькими. Какой блокнот трогать в запросе, задаёт параметр notebook (при одном блокноте он подставляется сам). Если ключ утечёт, под угрозой только его блокноты, а не весь аккаунт.

У ключа есть скоуп: write (по умолчанию — создавать, менять, удалять) или read — только чтение: запросы на запись такой ключ отклоняет (403 api.read_only). Read-only ключом безопаснее делиться, если приложению нужно лишь читать.

Только незашифрованные блокноты

Выдать ключ можно лишь для обычного блокнота. Для зашифрованного — нельзя: сервер не хранит ключей шифрования и физически не может зашифровать присланный текст.

Справочник (для разработчиков)

Все запросы — с заголовком Authorization: Bearer lm_live_…, тело и ответы — JSON в кодировке UTF-8. Эндпоинты:

Обновление без дублей: external_id + mode

Чтобы повторный экспорт обновлял ту же заметку, а не плодил копии, пришлите свой стабильный идентификатор external_id и режим upsert:

curl -X POST https://leavemessage.me/api/v1/notes \
  -H "Authorization: Bearer lm_live_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"atlas:pushkin:macro","mode":"upsert","title":"Пушкин","body":"# Маршрут\n…"}'

• mode: create (по умолчанию) — всегда новая заметка;
• mode: upsert — есть заметка с таким external_id в блокноте → обновить, нет → создать (нужен external_id);
• mode: append — то же, но body дописывается в конец через пустую строку (удобно копить в один документ).

Ответ (201 — создано, 200 — обновлено):

{
  "action": "created",
  "note": {
    "id": 128,
    "external_id": "atlas:pushkin:macro",
    "notebook": { "id": 42, "name": "Атлас — макро" },
    "title": "Пушкин",
    "body": "# Маршрут…",
    "url": "https://leavemessage.me/note/128",
    "is_sealed": false,
    "created_at": "2026-07-30T14:01:34Z",
    "updated_at": "2026-07-30T14:01:34Z"
  }
}

url — прямая ссылка на заметку (можно сразу дать редактору «открыть»). action: created / updated / appended / replayed.

Полезные мелочи

• Без дублей при ретраях. Заголовок Idempotency-Key с уникальной строкой — повтор того же запроса в течение 24 ч вернёт ту же заметку (action: replayed), а не создаст новую.
• Защита от затирания. Если заметку между выгрузками правит человек, перезапись затёрла бы его правки. Поэтому: (1) перед каждой перезаписью прежнее состояние уходит в историю — затёртое восстановимо через …/notes/{id}/versions; (2) можно прислать base_version (токен version из прошлого ответа) — если заметка изменилась, придёт 409 api.conflict с актуальным состоянием, а не тихое затирание.
• Проверка существования. GET /api/v1/notes?external_id=… вернёт массив из 0 или 1 заметки.
• Несколько блокнотов. Если у ключа их несколько, укажите notebook (id) в теле POST или ?notebook= в GET; без него — 422 api.notebook_required со списком в meta.notebooks. GET /api/v1/notebook без параметра вернёт список блокнотов ключа.
• Пакетно. POST /api/v1/notes/batch с телом {"notes":[…]} (до 50) — несколько заметок одним запросом и одним хитом лимита. Всё-или-ничего: один невалидный элемент → не применяется ничего (422 api.batch_failed, статус по каждому в results).
• Проверка без записи. ?dry_run=1 (или "dry_run":true) на POST /notes и /notes/batch — прогнать валидацию (лимиты, режим, версии) и получить {"dry_run":true,"would":…}, ничего не создавая. Невалидный запрос вернёт ту же ошибку, что и боевой.
• Лимит частоты — 60 запросов/мин на ключ. В каждом ответе: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; при превышении — 429 с Retry-After.
• Лимиты размера: title ≤ 255 и external_id ≤ 150 — именно символов, не байт (кириллица считается как есть); body ≤ 256 КБ (байты UTF-8). Превышение — явная ошибка, не «тихое» обрезание.
• Markdown рендерится как в редакторе: таблицы, блоки кода с подсветкой, списки, ---, задачи - [ ], индексы ~x~/^y^; формулы KaTeX с разделителями $…$ и $$…$$ (\(…\)/\[…\] — нет); один перенос строки = перенос; сырой HTML не рендерится; сноски не поддерживаются.

Ошибка приходит с HTTP-статусом ≥ 400 и телом {"error":{"code":"…","meta":{…}}} — поля message нет, code машинный (текст для пользователя составьте по нему):

Чего API пока не умеет

• Нет тегов и программного создания ключей — в планах.
• Заметка создаётся открытым текстом (без сквозного шифрования).