Перейти к основному содержимому

External API v1 — полное руководство по настройке внешнего приложения

Версия документа: 1.0 Версия API: v1 (это первая версия публичного External API; в будущем рядом будут существовать v2 и далее, документация по которым будет лежать в отдельных файлах с суффиксом v2/v3 в имени, не заменяя этот документ) Дата: 29.04.2026 Статус: Готов к обсуждению

Контекст: villas/admin-checklist/ Актуальный runtime: analytics.vitrip.store

Что это такое​

External API v1 позволяет внешнему приложению работать от имени реального пользователя системы.

Это значит:

  • внешнее приложение не получает сверхправ
  • оно видит только те проекты, разделы, чек-листы и пункты, которые видит сам пользователь
  • оно может выполнять только те действия, которые этому пользователю реально разрешены в интерфейсе

Проще говоря:

  • если пользователь может читать проект и менять статус пункта, то и внешнее приложение сможет это делать
  • если пользователь не видит проект или не имеет права менять deadline, внешний API этого тоже не позволит

Для кого этот документ​

Этот документ написан для человека, который:

  • не обязан быть программистом
  • может настроить внешнее приложение или сервис
  • хочет понять, как подключиться, какие методы использовать и что именно делает каждый метод

Что нужно подготовить заранее​

Перед использованием внешнего API нужно:

  1. Иметь обычный рабочий аккаунт в системе analytics.vitrip.store
  2. Войти в систему через браузер
  3. Открыть Профиль
  4. Создать персональный API-токен
  5. Вставить этот токен в настройки внешнего приложения

Важно:

  • токен показывается только один раз в момент создания
  • позже его повторно увидеть нельзя
  • если токен потерян, нужно отозвать его и создать новый

Базовый адрес API​

Все запросы идут на домен:

https://analytics.vitrip.store

Базовый путь v1:

https://analytics.vitrip.store/api/external/v1/

Версионирование API​

Этот документ описывает версию v1 External API. Версия зашита в URL — /api/external/v1/.... В будущем рядом с v1 будут жить независимые версии (v2, v3 и далее) параллельно, не заменяя предыдущие.

Принципы версионирования​

  1. Старые версии не ломаются. Когда выходит v2, v1 продолжает работать — клиенты, написанные под v1, не должны переписываться немедленно.
  2. Каждая версия — отдельный URL-неймспейс. /api/external/v1/ и /api/external/v2/ живут параллельно, имеют свои наборы эндпоинтов и могут различаться по семантике.
  3. Каждая версия — отдельная документация. Документы по v2 будут лежать рядом с этим файлом в reference/ под именами вида external-api-v2-full-reference.md и external-api-v2-quick-start.md. Этот документ (v1) при выходе v2 не переписывается — он остаётся каноничным справочником по v1.
  4. Срок жизни версии. У каждой версии есть явная политика поддержки. Когда v1 будет признан устаревшим (deprecated), это будет зафиксировано в шапке этого документа со статусом и ориентировочной датой окончания поддержки. До этого момента v1 остаётся production-ready.
  5. Что меняет мажорную версию. Несовместимые изменения семантики, удаление эндпоинтов, изменение формата ответа существующих эндпоинтов, изменение обязательных полей. Добавление новых полей в существующий ответ или новых эндпоинтов внутри v1 — обратно-совместимо и не требует выпуска новой мажорной версии.

Как клиенту понять, какую версию он использует​

  • По URL: префикс /api/external/v1/ — это v1, /api/external/v2/ — это v2.
  • Через GET /auth/me.php в ответе возвращается meta.api_version — это надёжный способ убедиться в активной версии.

Что делать клиенту при выходе следующей версии​

  1. Изучить документацию следующей версии (отдельный документ в reference/).
  2. Оценить, нужен ли переход (новые возможности, deprecation v1).
  3. Реализовать переход параллельно — без отключения работы по v1.
  4. После проверки переключить базовый URL клиента с v1/ на следующую версию.

Как получить токен​

Шаг 1. Войти в систему​

Откройте:

https://analytics.vitrip.store

Введите свой email и пароль и войдите как обычный пользователь.

Шаг 2. Открыть профиль​

В левом меню откройте:

Профиль

Шаг 3. Найти блок External API токени​

В профиле есть специальный раздел для работы с токенами.

Там можно:

  • создать новый токен
  • выбрать его название
  • выбрать срок действия
  • выбрать scope
  • посмотреть список уже созданных токенов
  • отозвать старый токен

Шаг 4. Создать токен​

При создании задаются:

  • Название токена
  • Срок действия
  • Scope

Шаг 5. Скопировать raw token​

После создания система покажет строку токена один раз.

Пример:

chk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Эту строку нужно:

  • сразу скопировать
  • сохранить в настройках внешнего приложения
  • не передавать посторонним

Что такое scope простыми словами​

Scope — это список разрешений для токена.

Если объяснить без технического языка:

  • scope определяет, что именно внешнее приложение сможет делать вашим токеном

Доступные scope​

auth:me​

Позволяет внешнему приложению проверить:

  • какой пользователь подключён
  • какие scope у токена
  • действует ли токен

projects:read​

Позволяет:

  • получать список доступных проектов
  • читать карточку проекта
  • читать дерево проекта

projects:search​

Позволяет искать внутри проекта:

  • по названию проекта
  • по разделам
  • по чек-листам
  • по пунктам
  • по ответам
  • по комментариям
  • по ссылкам

items:read​

Позволяет читать содержимое конкретного пункта:

  • статус
  • дедлайн
  • приоритет
  • комментарии
  • ответы
  • участников
  • вложения

items:status.write​

Позволяет менять статус пункта.

items:planning.write​

Позволяет менять плановые поля пункта:

  • дедлайн
  • приоритет
  • requires_answer

comments:write​

Позволяет добавлять комментарии в пункт.

answers:write​

Позволяет добавлять ответы в пункт.

items:materials.write​

Позволяет работать с материалами:

  • прикладывать изображения к item
  • прикладывать изображения к answer
  • обновлять document links

Как внешнее приложение должно подключаться​

Внешнему приложению обычно нужно 2 вещи:

  1. Базовый URL
  2. Bearer token

Базовый URL​

https://analytics.vitrip.store/api/external/v1/

Bearer token​

В каждом запросе должен передаваться заголовок:

Authorization: Bearer YOUR_TOKEN_HERE

Где YOUR_TOKEN_HERE — это ваш созданный токен.

Общая логика ответа API​

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

API отвечает примерно так:

{
  "ok": true,
  "data": {
    "...": "..."
  },
  "meta": {
    "request_id": "req_xxx",
    "api_version": "v1",
    "timestamp": "2026-04-29T11:17:32Z"
  }
}

Ответ с ошибкой​

Если что-то пошло не так:

{
  "ok": false,
  "error": {
    "code": "forbidden",
    "message": "У пользователя нет прав для этой операции"
  },
  "meta": {
    "request_id": "req_xxx",
    "api_version": "v1",
    "timestamp": "2026-04-29T11:17:32Z"
  }
}

Что означают частые ошибки​

401 unauthorized​

Токен не передан.

401 token_invalid​

Токен передан, но он неправильный.

401 token_revoked​

Токен был отозван.

401 token_expired​

Срок действия токена истёк.

403 scope_missing​

У токена нет нужного scope.

403 forbidden​

Scope есть, но сам пользователь не имеет такого права в системе.

404 not_found​

Сущность не найдена или недоступна этому пользователю.

422 validation_error​

Переданы неверные или неполные данные.

Полный список методов v1​

Ниже — практический список методов с простым объяснением.

1. Проверка токена и пользователя​

Метод​

GET /api/external/v1/auth/me.php

Что делает​

Показывает:

  • кто подключён
  • какой токен используется
  • какие у него scope

Когда использовать​

Всегда первым запросом после настройки внешнего приложения.

Пример​

curl -X GET \
  'https://analytics.vitrip.store/api/external/v1/auth/me.php' \
  -H 'Authorization: Bearer YOUR_TOKEN'

2. Список доступных проектов​

Метод​

GET /api/external/v1/projects/list.php

Параметры​

  • limit — сколько проектов вернуть
  • offset — с какого места начинать
  • archived — вернуть архивные проекты, если нужно

Что делает​

Возвращает список проектов, которые доступны этому пользователю.

Пример​

curl -X GET \
  'https://analytics.vitrip.store/api/external/v1/projects/list.php?limit=20&offset=0' \
  -H 'Authorization: Bearer YOUR_TOKEN'

3. Карточка одного проекта​

Метод​

GET /api/external/v1/projects/get.php?id=PROJECT_ID

Что делает​

Возвращает:

  • название проекта
  • описание
  • дедлайн
  • verdict
  • прогресс
  • счётчики

Пример​

curl -X GET \
  'https://analytics.vitrip.store/api/external/v1/projects/get.php?id=17' \
  -H 'Authorization: Bearer YOUR_TOKEN'

4. Дерево проекта​

Метод​

GET /api/external/v1/projects/tree.php?id=PROJECT_ID

Что делает​

Возвращает структуру проекта:

  • проект
  • разделы
  • чек-листы
  • пункты

Если у пользователя неполный доступ, вернётся только доступная часть дерева.

Пример​

curl -X GET \
  'https://analytics.vitrip.store/api/external/v1/projects/tree.php?id=17' \
  -H 'Authorization: Bearer YOUR_TOKEN'

5. Поиск внутри проекта​

Метод​

GET /api/external/v1/projects/search.php?id=PROJECT_ID&q=QUERY

Что делает​

Ищет внутри проекта по содержимому.

Можно искать:

  • название
  • текст пункта
  • ответы
  • комментарии
  • ссылки

Полезные параметры​

  • q — строка поиска
  • entity_type — ограничить поиск только по одному типу
  • item_id — точечный поиск по конкретному пункту
  • limit
  • offset

Примеры​

Поиск по слову​

curl -X GET \
  'https://analytics.vitrip.store/api/external/v1/projects/search.php?id=17&q=Тест' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Точный поиск по item_id​

curl -X GET \
  'https://analytics.vitrip.store/api/external/v1/projects/search.php?id=17&item_id=299' \
  -H 'Authorization: Bearer YOUR_TOKEN'

6. Детали одного пункта​

Метод​

GET /api/external/v1/items/get.php?id=ITEM_ID

Что делает​

Возвращает подробную карточку пункта:

  • текст
  • статус
  • дедлайн
  • приоритет
  • участники
  • комментарии
  • ответы
  • вложения
  • document links

Пример​

curl -X GET \
  'https://analytics.vitrip.store/api/external/v1/items/get.php?id=299' \
  -H 'Authorization: Bearer YOUR_TOKEN'

7. Смена статуса пункта​

Метод​

PATCH /api/external/v1/items/status.php

Формат​

Content-Type: application/json

Разрешённые статусы​

  • pending
  • in_progress
  • done
  • blocked

Пример body​

{
  "id": 299,
  "status": "in_progress"
}

Пример​

curl -X PATCH \
  'https://analytics.vitrip.store/api/external/v1/items/status.php' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"id":299,"status":"in_progress"}'

8. Изменение planning-полей пункта​

Метод​

PATCH /api/external/v1/items/planning.php

Что можно менять​

  • deadline
  • priority
  • requires_answer

Пример body​

{
  "id": 299,
  "priority": "high",
  "requires_answer": true
}

Формат priority​

  • low
  • medium
  • high

Пример​

curl -X PATCH \
  'https://analytics.vitrip.store/api/external/v1/items/planning.php' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"id":299,"priority":"high","requires_answer":true}'

9. Добавление комментария​

Метод​

POST /api/external/v1/comments/create.php

Что делает​

Добавляет комментарий в пункт.

Важно:

  • комментарий — это только текст
  • файлы и links в комментарии не поддерживаются

Пример body​

{
  "item_id": 299,
  "text": "Проверили интеграцию, продолжаем работу"
}

Пример​

curl -X POST \
  'https://analytics.vitrip.store/api/external/v1/comments/create.php' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"item_id":299,"text":"Проверили интеграцию, продолжаем работу"}'

10. Добавление ответа​

Метод​

POST /api/external/v1/answers/create.php

Что делает​

Создаёт содержательный ответ по пункту.

Ответ может содержать:

  • текст
  • document links

Пример body​

{
  "item_id": 299,
  "text": "Готово, первый этап завершён",
  "document_links": [
    {
      "kind": "document",
      "title": "Отчёт",
      "url": "https://example.com/report"
    }
  ]
}

Пример​

curl -X POST \
  'https://analytics.vitrip.store/api/external/v1/answers/create.php' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"item_id":299,"text":"Готово, первый этап завершён","document_links":[{"kind":"document","title":"Отчёт","url":"https://example.com/report"}]}'

11. Обновление ссылок пункта​

Метод​

PUT /api/external/v1/items/links.php

Что делает​

Полностью заменяет список document_links у пункта.

Важно:

  • это не "добавить одну ссылку сверху"
  • это именно "записать итоговый список ссылок"

Пример body​

{
  "id": 299,
  "document_links": [
    {
      "kind": "document",
      "title": "Техническое задание",
      "url": "https://example.com/spec"
    }
  ]
}

Пример очистки ссылок​

{
  "id": 299,
  "document_links": []
}

12. Загрузка изображений в пункт​

Метод​

POST /api/external/v1/items/attachments.php

Формат​

multipart/form-data

Что важно знать​

Сейчас runtime принимает изображения, а не любые файлы.

Практически это значит:

  • текстовый файл не пройдёт
  • корректное изображение пройдёт

Поля​

  • item_id
  • attachments[]

Пример​

curl -X POST \
  'https://analytics.vitrip.store/api/external/v1/items/attachments.php' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'item_id=299' \
  -F 'attachments[]=@image.png'

13. Загрузка изображений в answer​

Метод​

POST /api/external/v1/answers/attachments.php

Формат​

multipart/form-data

Поля​

  • answer_id
  • attachments[]

Пример​

curl -X POST \
  'https://analytics.vitrip.store/api/external/v1/answers/attachments.php' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'answer_id=23' \
  -F 'attachments[]=@image.png'

Полный сценарий работы — от начала до конца​

Ниже — практический сценарий, как это должно происходить в жизни.

Сценарий 1. Человек подключает внешнее приложение​

Шаг 1. Войти в систему​

Пользователь заходит в:

https://analytics.vitrip.store

и входит по своему обычному логину и паролю.

Шаг 2. Открыть профиль​

Пользователь открывает:

Профиль

Шаг 3. Создать токен​

Пользователь:

  • задаёт понятное имя токена Например:

    • CRM integration
    • Assistant
    • Automation bot

  • выбирает срок действия

  • выбирает нужные scope

Если приложению нужно:

  • только читать проекты и искать пункты — достаточно read scope
  • читать и менять статусы/планирование — добавляются write scope

Шаг 4. Скопировать токен​

После создания система показывает токен только один раз.

Пользователь копирует его и сохраняет во внешнем приложении.

Шаг 5. Открыть настройки внешнего приложения​

Во внешнем приложении нужно указать:

  • Base URL
  • Bearer token

Пример:

  • Base URL:
https://analytics.vitrip.store/api/external/v1/
  • Token:
chk_xxxxxxxxxxxxxxxxxxxxxxxxxxx

Шаг 6. Внешнее приложение делает первый технический запрос​

Первый запрос должен быть:

GET /auth/me.php

Задача этого запроса:

  • проверить, что токен рабочий
  • понять, под каким пользователем приложение авторизовано
  • понять, какие scope у токена

Шаг 7. Внешнее приложение получает список проектов​

Следующий запрос:

GET /projects/list.php

Так приложение понимает:

  • какие проекты видит пользователь
  • с какими можно работать

Шаг 8. Внешнее приложение открывает конкретный проект​

Например:

GET /projects/get.php?id=17

и затем:

GET /projects/tree.php?id=17

Так приложение получает структуру:

  • разделы
  • чек-листы
  • пункты

Шаг 9. Внешнее приложение ищет нужный пункт​

Например, по ключевому слову:

GET /projects/search.php?id=17&q=Тест

или по конкретному item_id, если он уже известен.

Это главный рабочий сценарий:

  1. знаем проект
  2. ищем по содержимому
  3. находим нужный пункт
  4. работаем уже по точному item_id

Шаг 10. Внешнее приложение читает карточку пункта​

GET /items/get.php?id=299

После этого оно видит:

  • статус
  • дедлайн
  • комментарии
  • ответы
  • вложения
  • ссылки

Шаг 11. Внешнее приложение делает точечное действие​

Например:

  • меняет статус
  • добавляет комментарий
  • добавляет ответ
  • добавляет ссылку
  • загружает изображение

Шаг 12. Система логирует действия​

Каждый вызов фиксируется в системе.

Что это даёт:

  • можно разбирать инциденты
  • можно видеть, что делал токен
  • можно понимать, какое приложение вызывало API

Шаг 13. При необходимости токен отзывается​

Если внешний сервис больше не нужен, пользователь:

  • снова открывает профиль
  • находит токен
  • нажимает Отозвать

После этого все запросы с этим токеном перестают работать.

Практический рабочий сценарий для внешнего приложения​

Ниже — рекомендуемая последовательность действий уже для самого внешнего приложения.

Правильная схема работы​

  1. Принять от пользователя:

    • base URL
    • bearer token

  2. Выполнить:

    • GET /auth/me.php

  3. Сохранить в настройках:

    • user.id
    • user.name
    • token.label
    • token.scopes

  4. Выполнить:

    • GET /projects/list.php

  5. Пользователь выбирает проект во внешнем приложении

  6. Выполнить:

    • GET /projects/get.php?id=...
    • GET /projects/tree.php?id=...

  7. Для поиска нужного пункта выполнять:

    • GET /projects/search.php?id=...&q=...

  8. После нахождения item_id выполнять:

    • GET /items/get.php?id=...

  9. Для действий использовать точечные endpoint-ы:

    • статус
    • planning
    • comments
    • answers
    • links
    • attachments

  10. Если API вернул 401, 403, 404 или 422:

    • показать человеку понятное сообщение
    • не пытаться обходить ограничения повторными хаками

Какой минимальный набор нужен большинству интеграций​

Если внешнему приложению не нужно всё сразу, обычно достаточно:

  • auth:me
  • projects:read
  • projects:search
  • items:read
  • comments:write

Если нужно менять статус:

  • добавить items:status.write

Если нужно менять дедлайн и приоритет:

  • добавить items:planning.write

Если нужно прикладывать изображения или ссылки:

  • добавить items:materials.write

Если нужно писать содержательные ответы:

  • добавить answers:write

Что важно помнить​

  1. API работает от имени пользователя, а не "сам по себе".
  2. Токен надо хранить как пароль.
  3. Если токен потерян — его надо отозвать.
  4. Scope лучше выдавать минимально необходимый.
  5. Для поиска пункта сначала лучше использовать projects/search.php, а уже потом работать по item_id.
  6. Для файлов нужен multipart/form-data.
  7. Для обычных write-запросов нужен application/json.

Итог​

Если упростить всё до одной фразы:

External API v1 — это безопасный способ дать внешнему приложению работать с проектами, пунктами, комментариями, ответами, ссылками и изображениями ровно в тех пределах, в которых это уже разрешено самому пользователю в интерфейсе.

Это правильная модель для:

  • CRM
  • внутренних ассистентов
  • automation-сервисов
  • интеграционных панелей
  • AI-агентов

без обхода прав и без ручной эмуляции браузера.

Каноничные правила и границы API v1​

Раздел фиксирует канонические правила, явно подтверждённые разработчиком API 29.04.2026 на основе результатов end-to-end smoke-теста через MCP-сервер chk-mcp. Эти правила являются частью контракта v1, не временными наблюдениями. Раздел нужно учитывать при разработке клиента и использовании API в production.

Уточнения к существующим эндпоинтам​

Минимальный рабочий размер изображения для attachments​

Эндпоинты POST /items/attachments.php и POST /answers/attachments.php принимают только изображения выше определённого нижнего порога. Изображения меньше порога отклоняются с 422 validation_error и сообщением «Запрос содержит невалидные данные».

  • Изображение 1×1 пиксель PNG — отклоняется (422).
  • Изображение 16×16 пикселей PNG — принимается.

Минимальный рабочий размер задокументирован в основной API-документации v1. На практике безопасно использовать изображения от 16×16 пикселей или больше. Если получаешь 422 при загрузке изображения — первое что проверить, это его размеры.

Конверсия в WebP​

Рантайм всегда конвертирует загруженное изображение в WebP независимо от исходного формата. В ответе:

  • original_name — имя исходного файла (*.png, *.gif и т.д.);
  • mime_type — image/webp;
  • path — r2://vitiana/.../<имя>.webp;
  • хранилище — Cloudflare R2;
  • URL для отдачи — /api/items/file.php?id=NNN или /api/answers/file.php?id=NNN.

Поле status_reset в ответе answers/attachments.php​

Эндпоинт загрузки изображений к ответу возвращает в payload поле status_reset: boolean. Когда true — это означает, что статус ответа был сброшен в pending в результате этой операции (например, если ответ уже был approved или rejected, и добавление вложений требует повторного review). При status_reset: false — статус ответа остался без изменений.

Клиент должен учитывать возможный side-effect при загрузке вложений в уже подтверждённый ответ.

Три каноничные формы передачи deadline​

Эндпоинт PATCH /items/planning.php принимает поле deadline в трёх формах, все три зафиксированы в API-документации v1 как поддерживаемые:

  • ISO-строка даты YYYY-MM-DD (например 2026-05-15) — устанавливает дедлайн;
  • null (явный JSON null) — очищает дедлайн (deadline: null в БД);
  • пустая строка "" — также очищает дедлайн (эквивалент null).

При разработке клиента можно полагаться на любой из этих способов очистки. Рекомендуется использовать явный JSON null — он самый каноничный и читаемый.

description пункта — read-only в v1​

Поле description присутствует в карточке пункта (ответ GET /items/get.php), но является read-only в External API v1 по архитектурному решению. Это не баг и не gap — это сознательно ограниченный scope первой версии контракта.

Изменение текстового описания пункта возможно только через веб-интерфейс системы. Для работы с описанием через программный интерфейс — следует ждать следующих версий API, где это направление будет расширено (см. раздел «Roadmap post-v1» ниже).

Канонические границы v1 (intentionally out of scope)​

Следующие функциональные направления сознательно не входят в первый контракт API v1. Это архитектурные решения по разделению ответственности версий, а не недоработки:

Verdict / rework — отдельный post-v1 слой​

Карточка пункта возвращает поля can_verdict, can_return_to_rework, verdict, rework_reason, rework_deadline, а также массив status_history с записями created, status_changed. Эти поля видны в read-эндпоинтах (для информации), но управление verdict-ом — одобрение, возврат на доработку с причиной и дедлайном — в v1 не реализовано.

Verdict-флоу зафиксирован разработчиком как отдельный post-v1 слой в roadmap API. Внешним клиентам и AI-агентам, которые ведут проект самостоятельно, эта возможность сейчас доступна только через веб-интерфейс. Это сделано чтобы не размывать границы первой версии.

Изменение содержимого пунктов / разделов / чек-листов / проектов​

В v1 закреплено правило: манипуляция в пределах существующей структуры, без создания/удаления/переименования контейнеров.

То есть через API v1 можно:

  • менять status, priority, deadline, requires_answer пункта;
  • добавлять comments, answers, attachments, links к пункту;
  • замещать document_links пункта целиком.

Через API v1 нельзя:

  • создавать или переименовывать проекты, разделы, чек-листы, пункты;
  • менять текст (text) или описание (description) уже существующего пункта;
  • удалять созданные comments, answers, attachments, links.

Это сознательное решение: первая версия — operational layer (управление состоянием существующих сущностей), а не structural editing layer (создание новых и реструктуризация). Создание контейнеров останется задачей веб-интерфейса до выхода соответствующих версий API.

Soft-archive / inactive вместо delete​

В системе в принципе нет понятия удаления — это решение по дизайну. Вместо delete планируется механизм перевода в неактивное / архивное состояние («ненужно»).

В v1 этот механизм не реализован, что зафиксировано как отдельное направление в roadmap разработчика API. Соответственно, в v1 нет DELETE-эндпоинтов для:

  • комментариев (POST /comments/create.php);
  • ответов (POST /answers/create.php);
  • вложений (POST /items/attachments.php, POST /answers/attachments.php);
  • ссылок в document_links.

Частичный обход для ссылок пункта: PUT /items/links.php с пустым массивом эквивалентен очистке всех ссылок (но не удалению одной конкретной).

Roadmap post-v1 (со стороны API)​

Подтверждённый разработчиком API roadmap для следующих версий:

  1. Расширение operational layer — возможные дополнения к v1 минорными версиями без breaking changes:
    • description пункта может стать writeable в minor-обновлении v1.
  2. Verdict / rework слой — отдельная мажорная версия (предположительно v2 или специализированный modular-эндпоинт), полноценный verdict workflow для внешних клиентов.
  3. Soft-archive / inactive — отдельное направление: перевод comments / answers / attachments в архивное состояние без физического удаления. Реализуется как PATCH-эндпоинт со статусом «ненужно» / «archived» / «inactive».
  4. Structural editing layer — создание/переименование/перемещение проектов, разделов, чек-листов, пунктов. Это целевое направление для v2.

Этот roadmap фиксируется здесь для согласования ожиданий клиентов API. Конкретные сроки и порядок реализации направлений принадлежат разработчику API.

Журнал подтверждений и наблюдений​

Раздел дополняется по мере накопления нового опыта и подтверждений со стороны разработчика API.

ДатаЭндпоинт / темаЗапись
29.04.2026items/attachments.phpИзображение 1×1 px отклоняется с 422 validation_error, 16×16 px принимается. Подтверждено и задокументировано в API v1 docs.
29.04.2026answers/attachments.phpПоле status_reset: boolean в ответе; зафиксирован side-effect ресета статуса при загрузке вложений в already-approved answer.
29.04.2026items/planning.phpТри каноничные формы deadline: ISO-строка / null / пустая строка "". Все три задокументированы в API v1 docs.
29.04.2026items/get.php (description)Поле description подтверждено как read-only в v1. Запись отложена в roadmap post-v1.
29.04.2026items/get.php (verdict)verdict / rework_* поля подтверждены как сознательно вне scope v1. Зафиксированы как отдельный post-v1 слой в roadmap API.
29.04.2026API v1 в целом (delete)Отсутствие DELETE-эндпоинтов подтверждено как архитектурное решение. Soft-archive / inactive занесён в roadmap post-v1.

Связанная документация​