vexdock-api

Vexdock API

Vexdock には CLI がありません。API がインターフェースのすべてで、ダッシュボードはそのクライアントの一つにすぎません。以下はすべて curl と jq を使用します。

セットアップ

環境変数は 2 つです。不足している場合はユーザーに尋ねてください。トークンを返答に含めてはいけません。

export VEXDOCK_URL=https://panel.example.com   # no trailing slash
export VEXDOCK_TOKEN=...                        # System → Settings → API tokens, shown once

シェルごとに一度だけ定義し、すべての呼び出しで使用してください。

vx() { curl -sS -H "Authorization: Bearer $VEXDOCK_TOKEN" -H 'Content-Type: application/json' "$VEXDOCK_URL$@"; }

確認：vx /api/me はアカウントを返します。vx /api/health（公開）は {"status":"healthy"} または 503 を返します。

セッション認証済みのコンテキストからトークンを作成するか、ユーザーに次の操作を依頼してください。 POST /api/tokens {"name":"agent"} → 201 {"token":{...},"value":"..."}。 value は二度と表示されません。DELETE /api/tokens/{id} で失効させます。

規約

• Bearer トークンを使う場合、CSRF ヘッダーは不要です。セッション Cookie には同一オリジンが必要です。スクリプトから使用しないでください。
• JSON ボディを使用し、Content-Type: application/json を指定します。不明なフィールドは 400 で拒否されます。
• エラー形式：{"error":{"code","message","details"?}}。コード：INVALID_REQUEST 400、 UNAUTHORIZED 401、CROSS_ORIGIN 403、NOT_FOUND 404、CONFIRMATION_REQUIRED 428、 CONFLICT 409、TASK_RUNNING 409、UNHEALTHY 409、GIT_PROVIDER_IN_USE 409、PROJECT_NOT_EMPTY 409、 DATABASE_NOT_RUNNING 409、STUDIO_UNSUPPORTED 400、QUERY_FAILED 400、 GIT_PROVIDER_UNAVAILABLE 400、GIT_PROVIDER_ERROR 502、CERTIFICATE_FAILED 502、INTERNAL 500。429 は Nginx がエンベロープなしで返します。
• ID は不透明な文字列です。一覧表示して名前から ID を特定してください。推測してはいけません。
• プロジェクトのルートは、?environment={id} が指定されていない限り、プロジェクトのデフォルト環境に対して動作します。 deploy、stop、services、services/export、deployments に適用されます。
• デプロイはただちに 202 を返します。deployment.status が success、failed、cancelled のいずれかになるまで GET /api/deployments/{id} をポーリングしてください（その間は queued／running）。または .../events をストリーミングしてください。
• exec またはタスクの run がゼロ以外の終了コードを返しても、応答は 200 です。exit_code を確認してください。
• 破壊的な呼び出し：ボリュームの削除と cleanup/volumes には ?confirm=true が必要です。環境を削除するとき、データも削除するには ?volumes=true を指定します。プロジェクトはサービスがなくなった場合にのみ削除できます（409 PROJECT_NOT_EMPTY）。いずれかのフラグを渡す前に、ユーザーに確認してください。すべての変更操作は監査ログに記録されます。
• ストリームは SSE です。curl -N を使い、event:／data: 行を読み取ってください。ターミナルは WebSocket です。代わりに POST .../exec を使用してください。

項目を探す

vx /api/projects | jq '.[] | {id, name, environments: [.environments[] | {id, name, is_default}]}'
vx /api/projects/$PROJECT/services | jq '.[] | {id, name, provider, state, status, health}'
vx /api/projects/$PROJECT/services?environment=$ENV
vx /api/docker/containers | jq '.[] | {id, name, state, managed}'
vx /api/domains | jq '.[] | {id, hostname, service, project_id}'
vx /api/tasks | jq '.[] | {id, name, schedule, service_name, project_name}'

デプロイして待機する

DEP=$(vx /api/services/$SERVICE/deploy -X POST | jq -r .id)     # or /api/projects/$PROJECT/deploy
until [ "$(vx /api/deployments/$DEP | jq -r .deployment.status)" != "queued" ] && \
      [ "$(vx /api/deployments/$DEP | jq -r .deployment.status)" != "running" ]; do sleep 3; done
vx /api/deployments/$DEP | jq '{status: .deployment.status, steps: [.steps[] | {name, status}]}'

ポーリングの代わりにライブログを使用する場合：curl -N -H "Authorization: Bearer $VEXDOCK_TOKEN" $VEXDOCK_URL/api/deployments/$DEP/events。

• キュー待ちまたは実行中に POST /api/deployments/{id}/cancel を実行します。
• POST /api/deployments/{id}/rollback は、そのデプロイに記録されたコミットを再デプロイします（コミットがない場合は 400）。
• POST /api/projects/{id}/stop は compose down を実行します。ボリュームは残ります。

サービス内でコマンドを実行する

vx /api/services/$SERVICE/exec -d '{"command":"php artisan migrate --force"}'
# → {"exit_code":0,"output":"..."}

shell は sh（デフォルト）または bash です。シェル構文（パイプ、&&、環境変数）が使えます。 サービスのコンテナ内で実行され、ホスト上では実行されません。10 分後に呼び出しはタイムアウトしますが、コマンドは実行を続けるため、再試行する前に状態を確認してください。出力が 1 MiB を超える場合は末尾が保持されます。コンテナは実行中である必要があります。

データベースをクエリする（Studio）

カタログに登録されたデータベースのみが対象です。マネージャーは compose ネットワーク経由で接続するため、公開ポートは不要です。

vx /api/services/$SERVICE/studio | jq '.schemas[] | {name, tables: [.tables[].name]}'
vx "/api/services/$SERVICE/studio/rows?schema=public&table=users&limit=20&sort=id&order=desc"
vx /api/services/$SERVICE/studio/query -d '{"schema":"public","query":"select count(*) from users"}'
# → {"columns":["count"],"rows":[["42"]],"affected":0,"duration_ms":3,"truncated":false}
vx /api/services/$SERVICE/studio/changes -d '{"schema":"public","table":"users","updates":[{"key":{"id":"7"},"values":{"name":"Ada"}}]}'

• すべてのセルは文字列または null です。UTF-8 以外のバイトは \x 形式の 16 進数で、MongoDB のフィールドは緩和形式の Extended JSON で返されます。
• where は URL エンコードされた JSON [{"column","op","value"}] です。op：eq neq gt gte lt lte contains starts_with is_null is_not_null。
• limit は 1～500 です。クエリ結果は 1,000 行で打ち切られます（truncated）。key が空のテーブルは読み取り専用です。
• クエリは SQL、MongoDB 用の Extended JSON コマンド 1 つ（{"find":"users","limit":5}）、 または Valkey 用のコマンドライン 1 つ（スキーマ db0、テーブル keys）です。自動コミットで実行されるため、書き込みは事前にユーザーに確認してください。
• QUERY_FAILED にはデータベース独自のエラーメッセージが含まれます。

パイプラインを使わないライフサイクル管理

vx /api/services/$SERVICE/start   -X POST
vx /api/services/$SERVICE/stop    -X POST
vx /api/services/$SERVICE/restart -X POST
vx /api/docker/containers/$CONTAINER/restart -X POST   # any container, managed or not

ログと統計

curl -N -H "Authorization: Bearer $VEXDOCK_TOKEN" "$VEXDOCK_URL/api/services/$SERVICE/logs"   # SSE: log, end
curl -N -H "Authorization: Bearer $VEXDOCK_TOKEN" "$VEXDOCK_URL/api/services/$SERVICE/stats"  # SSE: stats
vx "/api/services/$SERVICE/metrics?window=1h"     # 30m 1h 6h 24h 7d
vx "/api/system/metrics?window=24h"
vx /api/system/info

プロジェクトとサービス

vx /api/projects -d '{"name":"shop"}'                                    # 201
vx /api/services/$SERVICE -X PATCH -d '{"auto_deploy":true}'
vx /api/projects/$PROJECT -X DELETE                                      # only once it has no services

# git application
vx /api/projects/$PROJECT/services -d '{"name":"web","provider":"github","repository_url":"https://github.com/o/r","branch":"main"}'
# image
vx /api/projects/$PROJECT/services -d '{"name":"cache","provider":"image","image":"redis:7-alpine"}'
# database from the catalog (image, volume, credentials generated)
vx /api/projects/$PROJECT/services -d '{"name":"db","database":{"engine":"postgres","version":"17-alpine"}}'
vx /api/services/$SERVICE/database                                       # connection details
# pasted compose fragment
vx /api/projects/$PROJECT/services -d '{"name":"worker","provider":"raw","compose_fragment":"image: x\ncommand: run"}'

vx /api/services/$SERVICE -X PATCH -d '{"branch":"release"}'
vx /api/services/$SERVICE -X DELETE                                      # named volume is kept
vx /api/engines; vx /api/engines/postgres/versions

作成と編集ではコンテナは起動しません。後からデプロイしてください。provider は unconfigured、github|gitlab|bitbucket|gitea|git、image または raw です。Git 認証情報は、credential_kind の none|token|ssh_key と credential_secret （書き込み専用）、または接続済みプロバイダーの場合は git_provider_id、 owner、repository を使用します（GET /api/git-providers、.../{id}/repositories）。

変数

3 つのレイヤーがあり、すべて GET | PUT で、全体を書き込みます（PUT は一式を置き換えます）。

vx /api/projects/$PROJECT/variables        # every environment of the project
vx /api/environments/$ENV/variables        # this environment only; wins on collision
vx /api/services/$SERVICE/variables        # this service only
vx /api/services/$SERVICE/variables -X PUT -d '{"variables":[{"key":"APP_ENV","value":"production","is_secret":false},{"key":"APP_KEY","value":"...","is_secret":true}]}'

まず読み取り、マージしてから PUT してください。部分的なリストで PUT すると、残りは削除されます。 変更をコンテナに反映するにはデプロイが必要です。

環境

vx /api/projects/$PROJECT/environments
vx /api/projects/$PROJECT/environments -d '{"name":"staging","branch":"develop"}'
vx /api/environments/$ENV -X PATCH -d '{"branch":""}'   # "" = each service follows its own branch
vx /api/environments/$ENV -X DELETE                     # ?volumes=true; default env answers 400
vx "/api/projects/$PROJECT/deploy?environment=$ENV" -X POST

ドメイン

vx /api/domains -d '{"project_id":"'$PROJECT'","service":"web","hostname":"shop.example.com","container_port":3000,"https_enabled":true,"redirect_https":true}'
vx /api/domains/$DOMAIN/certificate -X POST              # issue/renew now; 502 CERTIFICATE_FAILED with reason
vx /api/domains/$DOMAIN -X DELETE

オプション：environment_id、certificate_source の letsencrypt|custom（および certificate_pem、private_key_pem）。vhost は保存されたものの証明書が保存されなかった場合、 作成／更新の応答に warning が含まれることがあります。その場合は certificate 経由で再試行してください。

スケジュールされたタスク

vx /api/services/$SERVICE/tasks -d '{"name":"prune","schedule":"0 3 * * *","timezone":"Europe/Warsaw","command":"php artisan model:prune"}'
vx /api/tasks/$TASK -X PATCH -d '{"enabled":false}'
vx /api/tasks/$TASK/run -X POST                          # answers with the finished run; 409 TASK_RUNNING if busy
vx "/api/tasks/$TASK/runs?limit=5"
vx /api/tasks/$TASK -X DELETE

5 フィールドの cron に加え、@hourly|@daily|@weekly|@monthly|@yearly を使用できます。マネージャーの停止中に逃した時刻の実行は再生されません。実行が 30 分を過ぎても続いている場合は、打ち切られます。ただし、そのプロセスは実行を続ける可能性があります。

Docker の整理

vx /api/docker/cleanup                                   # dry run: bytes per kind
vx /api/docker/cleanup/images -X POST                    # containers | images | networks | build-cache
vx "/api/docker/cleanup/volumes?confirm=true" -X POST    # ask the user first
vx /api/docker/images/pull -d '{"reference":"nginx:1.27"}'
vx "/api/docker/images/$IMAGE?force=true" -X DELETE
vx "/api/docker/volumes/$NAME?confirm=true" -X DELETE
vx /api/docker/containers/$CONTAINER/remove?force=true -X POST

システム

vx /api/system/settings                                  # PUT writes the whole object; cloudflare_api_token is write-only
vx /api/system/backup -X POST                            # ?volumes=true is slow and large; snapshot holds the master key
vx /api/system/backups; vx /api/system/backups/2026-01-05T031500 -X DELETE
vx /api/system/version; vx /api/system/version/check -X POST   # check_error set: latest is stale, says why
vx /api/system/update -X POST -d '{}'                    # latest on track; refuses 409 UNHEALTHY, 400 while check_error is set
vx /api/system/update -X POST -d '{"version":"v0.1.0-beta.100"}'   # a named tag skips the lookup
vx /api/system/update/status                             # phase: idle|backup|pulling|restarting|done|rolled-back
vx /api/system/certificates
vx /api/registries -d '{"name":"ghcr","url":"ghcr.io","username":"u","password":"..."}'   # login is verified on create

POST /api/system/update はマネージャーを再作成します。restarting 中は API が 1 分ほど停止するため、update/status をポーリングしてください。

作業スタイル

1. 一覧表示で ID を解決し、報告時には ID とともに名前を表示します。
2. 最も対象を絞った呼び出しを優先します。プロジェクトのデプロイよりサービスのデプロイを、再起動より exec を優先してください。
3. PUT エンドポイント（変数、設定）では、読み取り・変更・書き込みの手順を踏んでください。
4. 破壊的な呼び出しで削除されるものを伝え、confirm=true／volumes=true を指定する前に確認を得てください。
5. デプロイ後は status を報告し、失敗した場合は失敗したステップの名前も報告してください。ステップのログはイベントストリームにあります。
6. VEXDOCK_TOKEN、credential_secret、レジストリのパスワード、?secrets=true を指定したエクスポートを決してそのまま表示しないでください。

応答形式を含む完全なリファレンスは、Vexdock リポジトリの docs/api.md にあります。公開読み取り可能なエンドポイントは GET /api/health と GET /api/system/version のみです。