가장 작은 범위로 토큰을 만들어라
토큰은 패널의 계정 아래에서 생성되며 범위를 갖습니다: read, write, billing. write 가진 토큰은 서버를 주문할 수 있으므로, 유출되면 비용이 발생합니다. 모니터링 스크립트에는 read 만 부여하고 그 이상은 주지 마십시오.
그곳에서 사용할 만한 두 가지 설정이 있습니다: 만료 날짜와, 자동화가 실행되는 접두사에 토큰을 고정하는 소스 제한입니다. 둘 다 선택 사항입니다. 둘 다 비용이 들지 않습니다.
값은 한 번만 표시됩니다. 토큰 자체가 아니라 해시를 저장하기 때문입니다. 분실하면 새로 만들어야 합니다.
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를 재시도하면 의도와 다르게 서버가 두 대가 생길 수 있습니다. 키는 24시간 동안 기억되며 두 번째 인스턴스를 만들지 않고 원래 결과를 반환합니다. Cloud-init user-data는 같은 본문에 base64로 인코딩되어 user_data_b64 아래에 들어갑니다.
주문은 잔액이 첫 주기를 충당할 때 계정 잔액에서 차감됩니다. 그렇지 않으면 응답에는 인보이스와 결제 주소가 포함되며, 인보이스가 정산되면 인스턴스가 나타납니다.
속도 제한 및 오류
토큰당 분당 6백 건의 요청. 초과하면 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몇 초마다 폴링하거나, 웹훅을 등록하고 폴링을 완전히 중단하십시오. 웹훅은 서명되어 있습니다. 서명을 확인한 후에만 행동하십시오.
취소
패널에서 또는 다른 토큰으로 즉시 가능합니다:
curl -s -X DELETE https://paragonvps.com/api/v1/tokens/<token-id> -H "Authorization: Bearer $Paragon_TOKEN"진행 중인 요청은 완료되고 다음 요청은 401을 받습니다. 토큰이 유출된 것으로 의심되면 먼저 취소하고 조사하십시오. 토큰은 계정 이메일이나 2차 인증을 변경할 수 없지만, 확실히 돈을 쓸 수는 있습니다.
전체 참조, 모든 엔드포인트와 모든 필드는 /docs/api에 있습니다.