РОЗДІЛ 13

API-токени, REST і MCP

Усе, що є в консолі, доступне також як API та інструмент MCP. Один токен, троє дверей — з тими самими правами, що й у вас.

API-токени#

Токен дозволяє скрипту, завданню CI або ШІ-агенту діяти від вашого імені — з тими самими проєктами, тими самими правами й тим самим журналом аудиту. Створити токен можна на сторінці «Токени».

Натисніть + Новий токен і назвіть його за тим, що його використовуватиме (claude-code on my laptop, ci-deploy).
Скопіюйте Токен (dt_…) — зберігається лише його хеш, тому значення показується один раз.
Коли машину чи агента виведено з роботи, натисніть Відкликати в його рядку; відкликання діє з наступного ж виклику.

	JWT-токен доступу	API-токен
Як отримати	`POST /api/v1/auth/login`	сторінка «Токени» або `POST /api/v1/tokens`
Термін дії	8 годин	доки не відкликано
Найкраще підходить для	консолі, коротких скриптів	агентів і CI
Передається як	`Authorization: Bearer <value>`	`Authorization: Bearer dt_…`

Ставтеся до токена як до пароля

Він лежить у конфігурації клієнта відкритим текстом і дає повний доступ до всього, що вам належить. Відкликайте токени, якими більше не користуєтеся; створюйте по одному токену на кожен інструмент, щоб відкликати їх окремо.

REST API#

Базовий шлях /api/v1, тіла запитів у JSON, автентифікація bearer-токеном. Маршрути проєктів використовують числовий ідентифікатор проєкту. Тривалі операції (розгортання) відповідають 202, а стежити за ними можна через їхній журнал; журнали також передаються потоком як server-sent events.

Область	Маршрути
Автентифікація	`POST /auth/login` · `GET /auth/me`
Токени	`POST /tokens` · `GET /tokens` · `DELETE /tokens/{id}`
Проєкти	`GET /projects` · `POST /projects` · `GET /projects/{id}` · `DELETE /projects/{id}`
Завантаження	`POST /projects/{id}/uploads` (multipart `file`) · `PUT /uploads/{token}` (одноразове посилання)
Розгортання	`POST /projects/{id}/deployments` · `GET /projects/{id}/deployments` · `GET /deployments/{id}` · `GET /deployments/{id}/logs?stream=1`
Застосунок	`POST /projects/{id}/app/{start,stop,restart,recreate}` · `GET /projects/{id}/app` · `GET /projects/{id}/logs?tail=&follow=1`
Змінні	`GET /projects/{id}/env` · `PUT` / `DELETE /projects/{id}/env/{key}`
Бази даних	`POST` / `GET /projects/{id}/databases` · `GET` / `DELETE …/{name}` · `POST …/{name}/query` · `POST …/{name}/dump`
Домени	`POST` / `GET /projects/{id}/domains` · `DELETE …/{domain}` · `POST …/{domain}/precheck`
Резервні копії	`POST` / `GET /projects/{id}/backups` · `POST /backups/{id}/restore` · `DELETE /backups/{id}`
Сховище · метрики	`GET /users/me/storage` · `GET /metrics?scope=&range=`
Адміністрування	`GET`/`POST /users` · `PATCH`/`DELETE /users/{id}` · `GET`/`PUT /admin/settings` · маршрути обслуговування
Стан	`GET /health`

Коди помилок: 401 — неправильні або відсутні облікові дані, 404 — для всього, що вам не належить (ніколи 403), 409 — для конфлікту, наприклад дубліката slug, 413 — для завеликого завантаження, 422 — для некоректного введення.

MCP: хай агент керує платформою#

Платформа надає кожну свою можливість як інструмент MCP. Інструменти — це тонкі обгортки над тим самим сервісним шаром, що й консоль, тому агент підпорядковується точно тим самим правилам, що й ви.

Підключення Claude Code#

bash

claude mcp add --transport http dind-platform https://<your-platform-host>/mcp/ \
  --header "Authorization: Bearer <dt_… token>"

Запустіть claude і виконайте /mcp — dind-platform має відображатися як підключений разом зі своїми інструментами. Сторінка «Токени» показує цю команду в готовому до вставки вигляді, з уже підставленим вашим хостом.

Не пропускайте кінцеву косу риску

Адреса — /mcp/. Без косої риски сервер відповідає перенаправленням, а за проксі, що завершує TLS, таке перенаправлення може вести на http:// і втратити заголовок авторизації.

Транспорт	Адреса	Автентифікація
streamable HTTP	`https://<host>/mcp/` (або `http://<host>:8900/mcp/` на порту management)	`Authorization: Bearer <token>`, перевіряється під час кожного виклику інструмента
stdio	`DIND_PLATFORM_TOKEN=<token> python -m app.mcp.stdio`	змінна середовища, для локальних агентів

33 інструменти#

Кожен інструмент, прив'язаний до проєкту, приймає project як ідентифікатор (з list_projects) або як slug. Інструменти лише для адміністратора відхиляють звичайних користувачів із повідомленням tool requires the admin role.

Область	Інструменти
Платформа	`platform_health` · `get_metrics`
Користувачі (адмін)	`list_users` · `create_user` · `set_user_db_dind`
Проєкти	`list_projects` · `get_project` · `create_project`
Домени	`add_domain` · `domain_status` · `retry_precheck`
Розгортання	`upload_archive` · `create_upload_url` · `deploy_app` · `list_deployments` · `deploy_logs`
Застосунок	`app_start` · `app_stop` · `app_restart` · `app_recreate` · `get_logs`
Змінні	`list_env` · `set_env` · `unset_env`
Бази даних	`create_database` · `list_databases` · `drop_database` · `run_query` · `dump_database`
Сховище	`get_s3_credentials`
Резервні копії	`create_backup` · `list_backups` · `restore_backup`

Типовий сеанс з агентом#

ВиРозгорни ./api як «orders» на example.com із базою даних Postgres, а потім покажи мені перші рядки журналу.

create_project(slug="orders", display_name="Orders", base_domain="example.com") → ідентифікатор 12

create_database(project=12, name="main", engine="postgres") → postgres:17-alpine · пароль показується один раз

create_upload_url(project=12, filename="api.tar.gz") → одноразове PUT-посилання (15 хв)

термінал: curl -T api.tar.gz '<upload_url>' → upload_id 3f0c…

deploy_app(project=12, source_type="archive", upload_id="3f0c…") → розгортання #1 у черзі

deploy_logs(deployment_id=31) → # runtime=node version=24 … працює

АгентЗастосунок працює. Змінні бази даних DB_MAIN_* потрапили в застосунок, а перші рядки get_logs показують, що він слухає $PORT. Додати власний домен?

Розгортання асинхронні: агент запускає його, а потім опитує list_deployments або читає deploy_logs, доки статус не стане running або failed. Невдале розгортання залишає запущеною попередню версію.

Завантаження великого архіву#

upload_archive надсилає весь файл в одному MCP-запиті у форматі base64, а транспорт відхиляє запити понад 4 МіБ — на практиці це приблизно 3 МіБ архіву. Для більших файлів агент іде в обхід:

create_upload_url(project="myapp", filename="big.tar.gz")
  → {"upload_url": "https://<panel>/api/v1/uploads/upl_…", "method": "PUT",
     "expires_in_s": 900, "max_bytes": 536870912, "example_curl": "curl -sS -T big.tar.gz '…'"}

curl -sS -T big.tar.gz 'https://<panel>/api/v1/uploads/upl_…'
  → {"upload_id": "3f0c…e1.tar.gz", "size_bytes": 123456789}

deploy_app(project="myapp", source_type="archive", upload_id="3f0c…e1.tar.gz")

URL і є обліковими даними — заголовок не потрібен, — тому його свідомо обмежено:

одноразовий — перший же запит, що його пред'явить, спалює його, що б не сталося далі;
короткочасний — 15 хвилин, щоб почати запит (передавання, що вже триває, не переривається);
прив'язаний до одного проєкту, одного розширення файлу (.zip / .tar.gz) і користувача, який його запитав;
він лише зберігає файл — нічого не розгортається, доки не буде викликано deploy_app зі справжнім токеном;
до 512 МіБ; тіло запиту передається потоком на диск і перервається, щойно перевищить ліміт.

Помилки#

Помилки інструментів повертаються простим текстом із прапорцем MCP isError і ніколи не у вигляді стека викликів: збої автентифікації, власність (belongs to another user), стани доменів, як-от dns_failed, і помилки сервісів під час розгортань, резервного копіювання та роботи з базами даних.

Давайте агентам лише те, що їм потрібно

Створіть окремого користувача (це може зробити адміністратор) для автоматизації, яка має торкатися лише одного набору проєктів, і віддайте агенту його токен замість свого.