External API v1

Задачи, уведомления и лента активности для внешних сервисов

Первая версия внешнего API Trelio позволяет получить список проектов, участников и статусов, создать новую задачу, читать её состояние, точечно обновлять рабочие поля, добавлять комментарии, читать личные уведомления пользователя ключа, получать его ленту активности и скачивать вложения через Bearer API ключ.

Открыть OpenAPI JSON Открыть Trelio

Base URL: https://trelio.ru · Auth: Authorization: Bearer <API_KEY>

Владелец компании включает модуль Внешний API в настройках модулей.
В разделе API владелец или администратор создаёт персональный ключ. Владелец видит все ключи компании, администратор — только свои.
Сохраните секрет сразу после создания: Trelio больше его не покажет.
Получите доступные проекты через GET /api/external/v1/companies/:companySlug/projects.
Для нужного проекта вызовите task-create-meta, чтобы получить статусы, постановщиков и участников.
Создайте задачу через POST /api/external/v1/companies/:companySlug/tasks.
Проверяйте состояние через GET /tasks или GET /projects/:projectSlug/tasks/:taskNumber.
Обновляйте статус, дедлайн, срочность, исполнителя, участников, добавляйте plain-text комментарии, читайте уведомления и ленту активности пользователя ключа.

Для надёжных повторных вызовов всегда передавайте idempotencyKey. Если тот же ключ уже был использован с тем же телом запроса, API вернёт ту же задачу с флагом meta.isReplay = true.

Список проектов

curl -s \
  -H "Authorization: Bearer <API_KEY>" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/projects"

Метаданные для создания задачи в проекте

curl -s \
  -H "Authorization: Bearer <API_KEY>" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/projects/<PROJECT_SLUG>/task-create-meta"

Дополнительно доступны отдельные методы: /members и /statuses. Но для сценария постановки задачи чаще всего достаточно одного вызова task-create-meta.

Список задач с фильтрами

curl -s \
  -H "Authorization: Bearer <API_KEY>" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/tasks?projectSlug=operations&statusKind=active&dueAtFrom=2026-06-18&dueAtTo=2026-06-30&urgency=2&limit=50"

Карточка по проекту и номеру

curl -s \
  -H "Authorization: Bearer <API_KEY>" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/projects/operations/tasks/42"

Смена статуса

curl -s \
  -X PATCH \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/projects/operations/tasks/42/status" \
  -d '{ "statusCode": "review" }'

Для обновлений нужны scope tasks:update и активный участник, которым был создан ключ. Backend использует те же правила переходов статусов, дедлайнов, истории и уведомлений, что и обычный UI.

Экспорт задач за период

curl -s \
  -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/exports/json" \
  -d '{
    "scope": "all",
    "dateFrom": "2026-05-04",
    "dateTo": "2026-05-10"
  }'

Метод требует scope exports:read и возвращает тот же формат trelio-json-export/v4, который используется во встроенном экспорте.

ZIP-архив с export.json и файлами вложений

curl -s \
  -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/exports/zip" \
  -d '{
    "scope": "all",
    "dateFrom": "2026-05-04",
    "dateTo": "2026-05-10"
  }' \
  --output trelio-export.zip

ZIP использует тот же scope exports:read, что и JSON-выгрузка. В архив попадает export.json и доступные активные файлы вложений; удалённые или уже очищенные файлы отмечаются в metadata экспорта как missing.

Plain-text комментарий

curl -s \
  -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/projects/operations/tasks/42/comments" \
  -d '{
    "bodyText": "Заявка обновлена во внешней системе. Новый SLA: 2 рабочих дня."
  }'

Метод требует scope comments:create. bodyText всегда считается plain text: Markdown-разметка в этом поле не разбирается. Текст конвертируется во внутренний rich-text документ, попадает в обычную ленту комментариев задачи и запускает штатные уведомления.

Markdown-комментарий

curl -s \
  -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/projects/operations/tasks/42/comments" \
  -d '{
    "bodyMarkdown": "## Итог\\n\\n**SLA обновлён** до 2 рабочих дней.\\n\\n- Клиент уведомлён\\n- Документы приложены\\n\\n[Открыть источник](https://example.com/ticket/42)"
  }'

bodyMarkdown конвертируется в rich-text Trelio: поддерживаются жирный, курсив, зачёркивание, заголовки, списки, ссылки, inline code, code block, цитаты и таблицы. HTML в Markdown отключён. Markdown-картинки не создают вложения и не обходят upload-flow: они сохраняются как текст или ссылка. Поля bodyText и bodyMarkdown взаимоисключающие; в ответе comment.bodyText остаётся plain-text представлением сохранённого комментария.

Скачать конкретное вложение из task payload

curl -L \
  -H "Authorization: Bearer <API_KEY>" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/tasks/<TASK_ID>/attachments/<ATTACHMENT_ID>/download" \
  --output attachment.bin

Метод требует scope attachments:read. Сначала получите задачу через tasks:read: поле task.attachments[] содержит id, имя файла, MIME, размер и готовый downloadUrl. Endpoint отдаёт только активные вложения задач; deleted/retention файлы через внешний API не скачиваются.

Личные уведомления пользователя API ключа

curl -s \
  -H "Authorization: Bearer <API_KEY>" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/notifications?state=unread&limit=50"

Отметить уведомление прочитанным

curl -s \
  -X PATCH \
  -H "Authorization: Bearer <API_KEY>" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/notifications/<NOTIFICATION_ID>/read"

Отметить все уведомления прочитанными

curl -s \
  -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/notifications/read-all"

Лента активности как на /:companySlug/feed/

curl -s \
  -H "Authorization: Bearer <API_KEY>" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/activity-feed?limit=50"

Уведомления и лента активности всегда читаются от имени пользователя, который создал API ключ. Ключ перестаёт работать, если этот пользователь больше не активный владелец или администратор компании.

Пример запроса

curl -s \
  -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  "https://trelio.ru/api/external/v1/companies/<COMPANY_SLUG>/tasks" \
  -d '{
    "projectSlug": "operations",
    "title": "Проверить утренний отчёт по доставкам",
    "statusCode": "todo",
    "createdByMemberId": "11111111-1111-1111-1111-111111111111",
    "assigneeMemberId": "22222222-2222-2222-2222-222222222222",
    "participantMemberIds": [
      "33333333-3333-3333-3333-333333333333"
    ],
    "dueAt": "2026-04-03",
    "descriptionText": "Сверить цифры с внешним отчётом и отметить расхождения.",
    "checklists": [
      {
        "title": "Проверка",
        "items": [
          { "content": "Скачать CSV из внешней системы" },
          { "content": "Сверить суммы", "isCompleted": true }
        ]
      }
    ],
    "urgency": 1,
    "idempotencyKey": "ops-report-2026-04-03"
  }'

Что можно передать

projectSlug, title, idempotencyKey обязательны.
statusCode не обязателен: если его нет, используется initial-статус проекта.
createdByMemberId не обязателен: если его нет, используется участник, привязанный к API ключу.
assigneeMemberId и participantMemberIds должны ссылаться на активных участников проекта.
dueAt принимается в формате YYYY-MM-DD.
descriptionText сохраняется как plain text, сервер сам конвертирует его во внутренний rich-text документ.
checklists создаются сразу вместе с задачей в одной транзакции.
urgency принимает значения от 0 до 3.

401: ключ не передан или невалиден.
403: ключ не принадлежит компании, не хватает scope или проект архивирован.
404: компания, проект или активная задача не найдены.
400: ошибка в данных запроса, например несуществующий statusCode или недопустимый memberId.
409: тот же idempotencyKey уже использовался с другим телом запроса.

Внешние идентификаторы для интеграций: проект projectSlug, статус statusCode, люди memberId. Не завязывайте интеграцию на отображаемые имена.

Projects Members Statuses Task Create Meta Tasks Read Tasks Create Tasks Update Comments Create Notifications Activity Feed Attachments JSON/ZIP Export

projects:read
project_members:read
project_statuses:read
task_create_meta:read
tasks:read
tasks:create
tasks:update
comments:create
notifications:read
notifications:update
activity_feed:read
attachments:read
exports:read

Машинно-читаемая спецификация доступна по ссылке ниже. Её можно импортировать в Postman или использовать для генерации клиента.

Скачать OpenAPI JSON

Задачи, уведомления и лента активности для внешних сервисов

Быстрый старт

Discovery endpoint-ы

Чтение и обновление задач

JSON и ZIP-выгрузка

Комментарии

Вложения задач

Уведомления и лента активности

Создание задачи

Ошибки и правила