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 после использования.

Карточки

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

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

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

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

{
  "items": [
    {
      "id": "01900000-0000-7000-8000-000000000001",
      "title": "Тестовые данные",
      "version": 3
    }
  ],
  "nextCursor": null
}
GET/cardsПолучить активные Cardcards:read
POST/cardsСоздать Cardcards:write
GET/cards/{cardId}Получить Cardcards:read
PATCH/cards/{cardId}Изменить Cardcards:write
POST/cards/{cardId}/archiveАрхивировать Cardcards:write

Комментарии

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

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

Документы

CRUD Markdown Documents и управление их архивным состоянием.

GET/documentsПолучить Documentsdocuments:read
POST/documentsСоздать Documentdocuments:write
GET/documents/{documentId}Получить Documentdocuments:read
PATCH/documents/{documentId}Изменить Documentdocuments:write
POST/documents/{documentId}/archiveАрхивировать Documentdocuments:write
POST/documents/{documentId}/restoreВосстановить Documentdocuments:write

Scopes

cards: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.