Agent API — доступ внешним агентам

Получение API-ключа

Управление ключами (/api/agent/keys*) работает только по браузерной сессии — bearer-токен не даёт создавать/спискивать/отзывать ключи (иначе ключ мог бы плодить ключи).

Создать ключ

# Нужна сессия (cookie) залогиненного пользователя — например, скопировать Cookie из браузера
curl -X POST https://trelka.ru/api/agent/keys \
  -H 'Content-Type: application/json' \
  -H 'Cookie: <next-auth.session-token=...>' \
  -d '{"name": "my-agent"}'

Ответ 201 (токен — только здесь):

{
  "data": {
    "id": "3f2c…uuid",
    "name": "my-agent",
    "token": "trelka_<64 hex символов>"
  }
}

Сохраните token. Дальше он используется во всех запросах ниже.

Список своих ключей

curl -X GET https://trelka.ru/api/agent/keys -H 'Cookie: <next-auth.session-token=...>'

Ответ 200 (без токена и без хэша):

{
  "data": [
    {
      "id": "3f2c…uuid",
      "name": "my-agent",
      "created_at": "2026-08-17T12:00:00.000Z",
      "last_used_at": null,
      "revoked_at": null
    }
  ]
}

Отозвать ключ

curl -X DELETE https://trelka.ru/api/agent/keys/3f2c…uuid -H 'Cookie: <next-auth.session-token=...>'

Ответ 204 No Content. После отзыва ключ перестаёт аутентифицироваться (401).

Агент-эндпоинты

Доступны и по bearer-токену, и по браузерной сессии.

Список досок

curl -X GET https://trelka.ru/api/agent/boards -H 'Authorization: Bearer <token>'

Ответ 200 — доски, где пользователь участник (role: owner | member):

{
  "data": [
    {
      "id": "…uuid",
      "title": "Sprint 42",
      "description": null,
      "owner_id": "…uuid",
      "created_at": "2026-08-17T12:00:00.000Z",
      "updated_at": "2026-08-17T12:00:00.000Z",
      "role": "owner"
    }
  ]
}

Полное дерево доски

Один запрос — вся доска: списки, карточки, метки, чеклисты, комментарии (с автором-имейлом).

curl -X GET https://trelka.ru/api/agent/boards/<board_id> -H 'Authorization: Bearer <token>'

Ответ 200:

{
  "data": {
    "id": "…uuid",
    "title": "Sprint 42",
    "description": null,
    "owner_id": "…uuid",
    "owner": { "id": "…uuid", "email": "owner@example.com" },
    "created_at": "2026-08-17T12:00:00.000Z",
    "updated_at": "2026-08-17T12:00:00.000Z",
    "role": "owner",
    "customLabels": [
      { "id": "…uuid", "board_id": "…uuid", "name": "Срочно", "color": "red" }
    ],
    "lists": [
      {
        "id": "…uuid",
        "title": "To Do",
        "board_id": "…uuid",
        "position": 0,
        "created_at": "2026-08-17T12:00:00.000Z",
        "cards": [
          {
            "id": "…uuid",
            "title": "Настроить CI",
            "description": "markdown…",
            "list_id": "…uuid",
            "position": 0,
            "due_date": "2026-08-20T00:00:00.000Z",
            "created_at": "2026-08-17T12:00:00.000Z",
            "updated_at": "2026-08-17T12:00:00.000Z",
            "labels": ["red", "blue"],
            "customLabels": [
              { "id": "…uuid", "board_id": "…uuid", "name": "Срочно", "color": "red" }
            ],
            "checklist": [
              { "id": "…uuid", "card_id": "…uuid", "title": "пункт", "is_checked": false, "position": 0 }
            ],
            "comments": [
              {
                "id": "…uuid",
                "author_id": "…uuid",
                "author_name": "Иван",
                "author_email": "owner@example.com",
                "content": "текст",
                "created_at": "2026-08-17T12:00:00.000Z",
                "updated_at": "2026-08-17T12:00:00.000Z"
              }
            ]
          }
        ]
      }
    ]
  }
}

Создать карточку

Один вызов: карточка + цветные метки + кастомные метки + чеклист.

curl -X POST https://trelka.ru/api/agent/boards/<board_id>/cards \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "listId": "<list_id>",
    "title": "Задача",
    "description": "опционально",
    "dueDate": "2026-08-20",
    "position": 0,
    "labelColors": ["red", "blue"],
    "customLabelIds": ["<label_id>"],
    "checklist": [
      { "text": "первый пункт" },
      { "text": "второй пункт", "isChecked": true }
    ]
  }'

Поля тела:

Ответ 201 — созданная карточка (структура как элемент cards выше).

Коды ошибок

Замечания

• Токен показывается один раз при создании; хранится в БД как SHA-256-хэш — восстановить токен по БД невозможно.
• last_used_at обновляется при каждом успешном использовании ключа.
• Не реализовано (бэклог): rate-limit, UI-страница управления ключами, scope read-only.