Публичный API и API-ключи

Ваши файлы Plank не обязаны оставаться внутри приложения. С помощью API-ключа вы можете читать — а при желании и изменять — документы в своих рабочих пространствах из собственных инструментов: скрипта, интеграции или помощника по коду вроде Claude Code, запущенного на вашем ноутбуке.

Это тот же самый API, который использует приложение Plank, но предоставленный как стабильная, версионированная поверхность под /v1, чтобы вы могли строить на нём, не опасаясь, что он изменится у вас под ногами.

Создание ключа

Откройте Настройки → API-ключи и нажмите Создать ключ. Вы выбираете:

• Название — метку, чтобы помнить, где он используется («Мой ноутбук», «Скрипт для отчётов»).
• Рабочие пространства — к каким рабочим пространствам ключ имеет доступ: к одному, нескольким или ко всем вашим рабочим пространствам. Ключ никогда не получит доступ к рабочему пространству, участником которого вы не являетесь.
• Доступ — Только чтение (список, чтение, поиск, скачивание) или Чтение и запись (а также создание, перезапись, перемещение, удаление).
• Срок действия (необязательно) — дата, после которой ключ перестаёт работать.

Ключ показывается один раз, сразу после создания — скопируйте его именно тогда. Plank хранит только защищённый хеш, поэтому показать его снова не сможет. Если вы его потеряете, отзовите ключ и создайте новый. Любой ключ можно отозвать в любой момент на том же экране, и он сразу перестанет работать.

Ключ выглядит как plank_pat_…. Относитесь к нему как к паролю: тот, у кого он есть, обладает выданным вами доступом.

Использование ключа

Отправляйте ключ в заголовке bearer в каждом запросе:

Authorization: Bearer plank_pat_xxxxxxxx

Всегда начинайте с whoami, чтобы узнать, какие рабочие пространства видит ключ, и их id — id рабочего пространства вы передаёте в каждый запрос к файлам.

# Узнать свой доступ
curl -H "Authorization: Bearer $PLANK_API_TOKEN" \
  https://api.plank.md/v1/whoami
# → { "user_id": "...", "token": { "can_write": true },
#     "workspaces": [ { "id": "ws_123", "slug": "q1-reports", "name": "Q1 Reports" } ] }

Затем читайте, перечисляйте, ищите и записывайте файлы в рабочем пространстве. Пути указываются относительно корня рабочего пространства (например, reports/q1.md).

WS=ws_123
BASE=https://api.plank.md/v1/workspaces/$WS
AUTH="Authorization: Bearer $PLANK_API_TOKEN"

# Список содержимого каталога
curl -H "$AUTH" "$BASE/files?path=reports"

# Чтение файла
curl -H "$AUTH" "$BASE/files/content?path=reports/q1.md"

# Поиск
curl -H "$AUTH" "$BASE/search?q=revenue"

# Всё дерево файлов
curl -H "$AUTH" "$BASE/tree"

# Запись (создание или перезапись) — нужен ключ с правом чтения и записи
curl -X PUT -H "$AUTH" -H "Content-Type: application/json" \
  "$BASE/files/content?path=reports/draft.md" \
  -d '{ "content": "# Draft\n\nHello." }'

# Перемещение / переименование
curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
  "$BASE/files/move" -d '{ "source": "reports/draft.md", "dest": "reports/final.md" }'

# Удаление
curl -X DELETE -H "$AUTH" "$BASE/files?path=reports/final.md"

PDF, изображения и другие бинарные файлы

Текстовые файлы передаются через API как есть. Бинарные файлы — PDF, изображения, документы Word и Excel — нужно передавать и получать в base64, иначе байты повредятся по дороге.

# Скачать бинарный файл на диск
curl -H "$AUTH" -H "Accept: application/octet-stream" \
  "$BASE/files/content?path=acts/scan.pdf" -o scan.pdf

# ...или в виде base64 внутри обычного JSON-ответа
curl -H "$AUTH" "$BASE/files/content?path=acts/scan.pdf&encoding=base64"

# Загрузить бинарный файл
curl -X PUT -H "$AUTH" -H "Content-Type: application/json" \
  "$BASE/files/content?path=acts/scan.pdf" \
  -d "{\"content\": \"$(base64 < scan.pdf | tr -d '\n')\", \"encoding\": \"base64\"}"

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

• Если base64 содержит недопустимые символы или смешивает два алфавита base64, запрос вернёт 400.
• Обрезанную (truncated) строку проверка распознать не может, поэтому для больших файлов сверяйте size из повторного чтения с размером исходного файла.
• Загрузка ограничена примерно 18 МБ на файл (лимит запроса 25 МБ минус накладные расходы base64).
• Скачивание с Accept: application/octet-stream — до 100 МБ; вариант ?encoding=base64 — до 25 МБ, поскольку base64 приходится держать в памяти как текст.
• Для обычных текстовых файлов параметр encoding указывать не нужно — для них ничего не меняется.

Ваша база данных рабочего пространства

Некоторые созданные агентом дашборды и CRM в Plank хранят свои данные в настоящих таблицах — базе данных рабочего пространства («Lightweight Apps»). Ваш ключ может читать и управлять этими таблицами тоже, с тем же уровнем доступа, который вы дали ему для файлов: ключи только для чтения могут перечислять таблицы, описывать их и запрашивать строки; ключи с правом чтения и записи также могут создавать таблицы и добавлять, обновлять или удалять строки.

BASE=https://api.plank.md/v1/workspaces/$WS
AUTH="Authorization: Bearer $PLANK_API_TOKEN"

# Список таблиц в этом рабочем пространстве
curl -H "$AUTH" "$BASE/app-data/tables"

# Описание столбцов таблицы
curl -H "$AUTH" "$BASE/app-data/tables/invoices"

# Запрос строк — фильтрация и сортировка через JSON-параметры
curl -H "$AUTH" "$BASE/app-data/tables/invoices/rows?where={\"status\":\"open\"}&orderBy={\"column\":\"total\",\"direction\":\"desc\"}&limit=25"

# Создание таблицы — нужен ключ с правом чтения и записи
curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
  "$BASE/app-data/tables" \
  -d '{ "name": "invoices", "columns": [ { "name": "customer", "type": "text" }, { "name": "total", "type": "numeric" } ] }'

# Добавление строки
curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
  "$BASE/app-data/tables/invoices/rows" \
  -d '{ "customer": "Acme Co", "total": 199.50 }'

# Обновление строки по id
curl -X PATCH -H "$AUTH" -H "Content-Type: application/json" \
  "$BASE/app-data/tables/invoices/rows/<row-id>" \
  -d '{ "status": "paid" }'

# Удаление строки по id
curl -X DELETE -H "$AUTH" "$BASE/app-data/tables/invoices/rows/<row-id>"

Краткая справка:

• Список таблиц — GET .../app-data/tables
• Описание таблицы — GET .../app-data/tables/:table (столбцы + типы)
• Чтение строк — GET .../app-data/tables/:table/rows (при необходимости фильтруйте через where и сортируйте через orderBy, оба в формате JSON)
• Создание таблицы — POST .../app-data/tables
• Добавление / обновление / удаление строки — POST / PATCH / DELETE на .../app-data/tables/:table/rows[/:id]

Вы можете создавать новые таблицы из собственных инструментов, но изменение структуры существующей таблицы — добавление, переименование или удаление столбца, а также добавление связи между таблицами — выполняется агентом внутри Plank, а не через этот API.

Использование вместе с Claude Code

Добавьте фрагмент вроде этого в файл CLAUDE.md своего проекта, чтобы помощник знал, как обращаться к вашим файлам Plank:

## Plank file access

My Plank business documents are available over the Plank public API.
- Base URL: https://api.plank.md/v1
- Auth: send header `Authorization: Bearer $PLANK_API_TOKEN` (the key is in my environment).
- First call `GET /whoami` to discover my workspace ids.
- For PDFs, images, or Office files add `&encoding=base64` when reading and send
  `{ "content": "<base64>", "encoding": "base64" }` when writing. Plain text needs neither.
- Then read files with `GET /workspaces/<id>/files/content?path=<relative/path>`,
  list with `/files?path=`, search with `/search?q=`, and (if needed) write with
  `PUT /workspaces/<id>/files/content?path=`.

Задайте ключ в своей оболочке, чтобы он никогда не попал в репозиторий (имя переменной выбираете вы — PLANK_API_TOKEN используется здесь просто как пример):

export PLANK_API_TOKEN=plank_pat_xxxxxxxx

Ограничения и хорошие практики

• Ограничивайте область доступа. Давайте ключу только те рабочие пространства и тот доступ (чтение или запись), которые ему действительно нужны. Ключ только для чтения ничего не сможет изменить, что делает его утечку гораздо менее опасной.
• Меняйте и отзывайте. Если ключ мог быть раскрыт, отзовите его и выпустите новый — это мгновенно.
• Лимиты частоты запросов. Запросы ограничены по частоте для каждого ключа; если вы выполняете большой объём работы пакетами, распределяйте нагрузку и обрабатывайте ответы 429, повторяя запрос через мгновение.
• Полный справочник. Полный, всегда актуальный справочник по эндпоинтам (OpenAPI) опубликован по адресу /v1/docs, а исходная спецификация — по адресу /v1/openapi.json; направляйте инструменты генерации кода именно туда.