pmlyДокументация
Открыть pmly
Ресурсы/Project API

Project API

Интегрируйте Card, комментарии и Markdown Documents одного Project через ограниченный Bearer token. API доступен на каноническом домене Organization.

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

Owner выпускает token в разделе Project API. Секрет показывается один раз, передаётся в заголовке Authorization и никогда не используется в browser URL.

Authorization: Bearer PMLY_PROJECT_TOKEN

Минимальные права. Выдавайте только scopes, необходимые конкретной интеграции, задавайте срок действия и отзывайте token после использования.

Карточки

Создание, настройка, порядок, архив и восстановление Board текущего Project.

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

curl --request GET \
  --url 'https://example-tenant.pmly.ru/api/v1/project-api/cards?limit=50' \
  --header 'Authorization: Bearer PMLY_PROJECT_TOKEN'

Пример ответа

{
  "cards": [
    {
      "id": "01900000-0000-7000-8000-000000000001",
      "boardId": "01900000-0000-7000-8000-000000000010",
      "columnId": "01900000-0000-7000-8000-000000000011",
      "title": "Тестовые данные",
      "description": "",
      "version": 3,
      "updatedAt": "2026-07-29T12:00:00Z",
      "archivedAt": null
    }
  ],
  "nextCursor": null
}
GET/boardsПолучить Board и Columnboards:read
POST/boardsСоздать Boardboards:write
GET/boards/archivedПолучить архив Boardboards:read
PATCH/boards/{boardId}Изменить Boardboards:write
POST/boards/{boardId}/moveПереместить Boardboards:write
POST/boards/{boardId}/archiveАрхивировать Board (также требуется cards:write)boards:write
POST/boards/{boardId}/restoreВосстановить Board (также требуется cards:write)boards:write

JSON для изменяющих запросов

Создание Board

Создаёт Board с четырьмя стартовыми Column в Project токена.

POST/boards
ПолеТипОбяз.Описание
namestringДаНазвание от 1 до 200 символов.
colorKeyBoardColorKeyДаЦвет из опубликованного каталога.
ЗаголовкиIdempotency-Key
{
  "name": "Запуск продукта",
  "colorKey": "cyan"
}

Изменение Board

Заменяет имя и цвет Board целиком.

PATCH/boards/{boardId}
ПолеТипОбяз.Описание
namestringДаПолное новое название.
colorKeyBoardColorKeyДаПолное новое значение цвета.
ЗаголовкиIf-Match
{
  "name": "Запуск v2",
  "colorKey": "green"
}

Порядок Board

Ставит Board между соседними anchors; без anchors перемещает в конец.

POST/boards/{boardId}/move
ПолеТипОбяз.Описание
previousBoardIdUUID | nullДаПредыдущая Board или null.
nextBoardIdUUID | nullДаСледующая Board или null.
ЗаголовкиIf-MatchIdempotency-Key
{
  "previousBoardId": null,
  "nextBoardId": null
}

Архивирование Board

Архивирует Board вместе с активными Card или переносит их в другую Board.

POST/boards/{boardId}/archive
ПолеТипОбяз.Описание
cardDispositionarchive_cards | transferДаСпособ обработки активных Card.
targetBoardIdUUID | nullНетОбязателен только для transfer.
ЗаголовкиIf-MatchIdempotency-Key
{
  "cardDisposition": "archive_cards",
  "targetBoardId": null
}

Комментарии

Discovery workflow и Label, создание, чтение, изменение и архивирование Card текущего Project.

GET/labelsПолучить каталог Labelcards:read
POST/labelsСоздать Labelcards:write
GET/cardsПолучить активные Cardcards:read
POST/cardsСоздать Cardcards:write
GET/cards/{cardId}Получить Cardcards:read
PATCH/cards/{cardId}Изменить Cardcards:write
POST/cards/{cardId}/moveПереместить Cardcards:write
PUT/cards/{cardId}/labelsЗаменить Label Cardcards:write
POST/cards/{cardId}/archiveАрхивировать Cardcards:write

JSON для изменяющих запросов

Создание Label

Создаёт Organization-wide Label. Требует cards:write и active owner Membership владельца token.

POST/labels
ПолеТипОбяз.Описание
namestringДаУникальное название от 1 до 80 символов после trim.
colorLabelColorДаОдин из gray, blue, green, yellow, orange, red, purple.
ЗаголовкиIdempotency-Key
{
  "name": "API",
  "color": "blue"
}

Создание Card

Создаёт Card в конкретной Column. Board и Column должны принадлежать Project, для которого выпущен token.

POST/cards
ПолеТипОбяз.Описание
boardIdUUIDДаИдентификатор Board внутри Project.
columnIdUUIDДаИдентификатор начальной Column внутри Board.
titlestringДаНазвание: от 1 до 500 символов после trim.
descriptionstringДаPlain text до 20 000 символов; пустая строка допустима.
ЗаголовкиIdempotency-Key
{
  "boardId": "01900000-0000-7000-8000-000000000010",
  "columnId": "01900000-0000-7000-8000-000000000011",
  "title": "Подготовить описание релиза",
  "description": "Собрать изменения и проверить ссылки."
}

Изменение Card

Заменяет название и описание Card. Оба поля передаются целиком; частичное изменение одного поля не поддерживается.

PATCH/cards/{cardId}
ПолеТипОбяз.Описание
titlestringДаПолное новое название: от 1 до 500 символов.
descriptionstringДаПолное новое plain-text описание до 20 000 символов.
ЗаголовкиIf-Match
{
  "title": "Подготовить описание релиза v2",
  "description": "Текст обновлён после ревью."
}

Перемещение Card

Перемещает Card в другую Column или меняет порядок. Без anchors Card добавляется в конец целевой Column.

POST/cards/{cardId}/move
ПолеТипОбяз.Описание
targetColumnIdUUIDДаЦелевая Column того же Board и Project.
previousCardIdUUID | nullНетCard, после которой нужно поставить перемещаемую Card.
nextCardIdUUID | nullНетCard, перед которой нужно поставить перемещаемую Card.
ЗаголовкиIf-MatchIdempotency-Key
{
  "targetColumnId": "01900000-0000-7000-8000-000000000012",
  "previousCardId": null,
  "nextCardId": null
}

Метки Card

Заменяет полный набор Label Card. UUID доступны через каталог Label; пустой массив снимает все метки.

PUT/cards/{cardId}/labels
ПолеТипОбяз.Описание
labelIdsUUID[]ДаДо 20 уникальных Label текущего Tenant.
ЗаголовкиIf-Match
{
  "labelIds": [
    "01900000-0000-7000-8000-000000000020"
  ]
}

Документы

Чтение обсуждения Card и публикация agent-authored комментариев.

GET/cards/{cardId}/commentsПолучить комментарииcomments:read
POST/cards/{cardId}/commentsДобавить комментарийcomments:write

JSON для изменяющих запросов

Создание комментария

Публикует комментарий от имени интеграции. Для обычного комментария достаточно поля text.

POST/cards/{cardId}/comments
ПолеТипОбяз.Описание
textstringДаТекст комментария: от 1 до 5 000 символов.
parentCommentIdUUID | nullНетРодительский комментарий для ответа; иначе null или поле можно не передавать.
mentionedUserIdsUUID[]НетУникальные ID упомянутых пользователей; по умолчанию пустой массив.
ЗаголовкиIdempotency-Key
{
  "text": "Описание проверено, можно публиковать.",
  "parentCommentId": null,
  "mentionedUserIds": []
}

Scopes

boards:readboards:writecards:readcards:writecomments:readcomments:writedocuments:readdocuments:write

Недостающий scope возвращает 403 PROJECT_API_SCOPE_REQUIRED.

Pagination

Списки используют cursor pagination. Передавайте opaque nextCursor как cursor; limit принимает от 1 до 100 и по умолчанию равен 50.

Idempotency и версии

Создающие и архивирующие команды принимают уникальный Idempotency-Key. Изменения существующего ресурса требуют canonical If-Match; устаревшая версия возвращает 409.

Ошибки

400Некорректный запрос или Idempotency-Key.
401Token отсутствует, неизвестен, истёк или отозван.
403Token не имеет необходимого scope.
404Ресурс не существует или находится в другом Project/Tenant.
409Конфликт версии или повтор команды с другим payload.
429Превышен rate limit; учитывайте retry metadata.