動作する最小スコープのトークンを作成する
トークンはパネルのアカウント下で作成され、スコープ read、write、billing を持ちます。write を持つトークンはサーバーを注文できるため、漏洩した場合、コストが発生します。監視スクリプトには read のみを付与し、それ以上は付与しないでください。
その際に使用する価値のある2つの設定: 有効期限と、自動化が実行されるプレフィックスにトークンを固定する送信元制限です。どちらも任意です。どちらも簡単です。
値は一度だけ表示されます。なぜなら、トークン自体ではなくハッシュを保存するからです。紛失した場合は、新しいものを作成する必要があります。
export Paragon_TOKEN=...無人で実行されるマシンで、シェル履歴よりも優れています:
systemd-creds encrypt token.txt /etc/credstore.encrypted/paragon-token最初の呼び出し
curl -s https://paragonvps.com/api/v1/account -H "Authorization: Bearer $Paragon_TOKEN" | jq .すべてがJSONで、すべてが /api/v1 の下にあり、すべての応答には request_id ヘッダーが含まれます。それをチケットに引用すれば、何時だったかを尋ねる代わりに、数秒で正確な呼び出しを見つけられます。
curl -s https://paragonvps.com/api/v1/instances -H "Authorization: Bearer $Paragon_TOKEN" | jq -r '.[] | .id + " " + .hostname + " " + .site + " " + .state'注文
curl -s -X POST https://paragonvps.com/api/v1/instances -H "Authorization: Bearer $Paragon_TOKEN" -H "Content-Type: application/json" -H "Idempotency-Key: 2026-07-16-edge-01" -d '{"plan":"r-8","site":"AMS-01","image":"debian-13","hostname":"edge-01","ssh_keys":["primary"]}'Idempotency-Key ヘッダーを送信してください。これなしでPOSTを再試行すると、2つのサーバーと1つの意図になることがあります。キーは24時間記憶され、2番目のインスタンスを構築する代わりに元の結果を返します。cloud-init のユーザーデータは、同じ本文に base64 エンコードして user_data_b64 の下に含めます。
注文は、残高が最初のサイクルをカバーする場合、アカウント残高から引き落とされます。それ以外の場合、応答には請求書と支払いアドレスが含まれ、請求書が決済されるとインスタンスが表示されます。
レート制限とエラー
トークンあたり毎分600リクエスト。超えると 429 と Retry-After ヘッダーが返されます。これは、ループ内の固定スリープに置き換えるのではなく、読むためのものです。
エラーは JSON で、code、人間向けの message、request_id が含まれます。ステータスはクラスを示します: 400 は正しくないものを送信した、401 はトークンが無効または失効済み、403 はトークンにスコープがない、404 は存在しないか、あなたのものではない、409 はインスタンスがその操作を実行できない状態、5xx は当社側の問題です。
ページネーションとポーリング
コレクションは ?page= と ?per_page= を受け取り、Link ヘッダーを返します。長時間の操作はブロックする代わりにジョブを返します。これには、プロビジョニング、移行、復元が含まれます:
curl -s https://paragonvps.com/api/v1/jobs/<job-id> -H "Authorization: Bearer $Paragon_TOKEN" | jq -r .stateそれを数秒ごとにポーリングするか、Webhook を登録してポーリングを完全に停止します。Webhook は署名されています。アクションを実行する前に署名を確認してください。
失効
パネルまたは別のトークンを使用して即時:
curl -s -X DELETE https://paragonvps.com/api/v1/tokens/<token-id> -H "Authorization: Bearer $Paragon_TOKEN"進行中のリクエストは完了し、次のリクエストは 401 を受け取ります。トークンが漏洩した疑いがある場合は、最初に失効させ、後で調査してください。トークンはアカウントのメールアドレスや2要素認証を変更できませんが、確実に資金を使うことができます。
完全なリファレンス、すべてのエンドポイントとすべてのフィールドは、/docs/api にあります。