Tạo mã API và thực hiện lệnh gọi đầu tiên

Tạo token với phạm vi nhỏ nhất có thể hoạt động

Token được tạo trong bảng điều khiển dưới tài khoản và mang các phạm vi: read, write, billing. Token có write có thể đặt máy chủ, nghĩa là token bị rò rỉ sẽ tốn tiền. Cấp cho script giám sát quyền read và không hơn.

Hai cài đặt đáng sử dụng khi bạn ở đó: ngày hết hạn và giới hạn nguồn gắn token với tiền tố mà tự động hóa của bạn chạy. Cả hai đều tùy chọn. Cả hai đều rẻ.

Giá trị chỉ hiển thị một lần, vì chúng tôi lưu hash của nó thay vì token. Mất nó có nghĩa là tạo một cái khác.

export Paragon_TOKEN=...

Tốt hơn lịch sử shell, trên máy chạy không giám sát:

systemd-creds encrypt token.txt /etc/credstore.encrypted/paragon-token

Cuộc gọi đầu tiên

curl -s https://paragonvps.com/api/v1/account -H "Authorization: Bearer $Paragon_TOKEN" | jq .

Mọi thứ đều là JSON, mọi thứ nằm dưới /api/v1, và mọi phản hồi đều mang header request_id. Trích dẫn header đó trong ticket và chúng tôi sẽ tìm thấy cuộc gọi chính xác trong vài giây thay vì hỏi bạn lúc đó là mấy giờ.

curl -s https://paragonvps.com/api/v1/instances -H "Authorization: Bearer $Paragon_TOKEN" | jq -r '.[] | .id + " " + .hostname + " " + .site + " " + .state'

Đặt một máy chủ

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"]}'

Gửi header Idempotency-Key. Thử lại POST mà không có header này là cách mọi người kết thúc với hai máy chủ và một ý định; khóa được ghi nhớ trong hai mươi bốn giờ và trả về kết quả ban đầu thay vì tạo phiên bản thứ hai. Cloud-init user-data nằm trong cùng body, mã hóa base64, dưới user_data_b64.

Đơn hàng sử dụng số dư tài khoản khi số dư đủ cho chu kỳ đầu tiên. Nếu không, phản hồi mang hóa đơn và địa chỉ thanh toán, và phiên bản xuất hiện sau khi hóa đơn được thanh toán.

Giới hạn tốc độ và lỗi

Sáu trăm yêu cầu mỗi phút cho mỗi token. Vượt qua và bạn nhận được 429 với header Retry-After, header này để đọc thay vì thay bằng lệnh sleep cố định trong vòng lặp.

Lỗi là JSON mang code, message cho con người và request_id. Trạng thái cho bạn biết loại lỗi: 400 bạn gửi sai thứ gì đó, 401 token không hợp lệ hoặc đã thu hồi, 403 token thiếu phạm vi, 404 nó không tồn tại hoặc không phải của bạn, 409 phiên bản ở trạng thái không thể thực hiện điều đó, và 5xx là lỗi của chúng tôi.

Phân trang và thăm dò

Bộ sưu tập nhận ?page= và ?per_page= và trả về header Link. Các thao tác dài giao cho bạn một công việc thay vì chặn, bao gồm cấp phát, di chuyển và khôi phục:

curl -s https://paragonvps.com/api/v1/jobs/<job-id> -H "Authorization: Bearer $Paragon_TOKEN" | jq -r .state

Thăm dò mỗi vài giây, hoặc đăng ký webhook và ngừng thăm dò hoàn toàn. Webhook được ký; kiểm tra chữ ký trước khi xử lý.

Thu hồi

Ngay lập tức, từ bảng điều khiển hoặc bằng token khác:

curl -s -X DELETE https://paragonvps.com/api/v1/tokens/<token-id> -H "Authorization: Bearer $Paragon_TOKEN"

Các yêu cầu đang chạy hoàn tất và yêu cầu tiếp theo nhận được 401. Nếu bạn nghi ngờ token bị rò rỉ, thu hồi trước và điều tra sau. Token không thể thay đổi email tài khoản hoặc yếu tố thứ hai của bạn, nhưng chắc chắn có thể tiêu tiền.

Tài liệu tham khảo đầy đủ, mọi endpoint và mọi trường, tại /docs/api.