DNS 관리 API

개요

한 영역은 하나의 도메인에 대한 레코드를 보유합니다. API를 통해 수행하는 모든 변경 사항은 VPS.org 네임서버로 즉시 푸시됩니다. 이 영역에서 도메인을 제공하려면 등록업체에서 네임서버를 ns1.vps.org, ns2.vps.org 및 ns3.vps.org로 설정합니다.

변경 사항은 한 단계에서 저장되고 게시됩니다. 네임서버가 변경을 거부하면 요청이 502를 반환하고 아무것도 저장되지 않습니다. 다른 계정이 이미 관리하는 도메인, 다른 계정의 부모 또는 자식 영역 또는 VPS.org 예약 이름에 대한 영역을 만들 수 없습니다.

필요한 권한: dns:list (GET), dns:create (POST), dns:update (PUT, PATCH, sync), dns:delete (DELETE), dns:*

얻다 /api/v1/dns-zones/

모든 DNS 영역 나열

페이지당 25개의 최신 영역을 반환합니다. 레코드는 여기에 포함되지 않습니다. 단일 영역을 가져오면 레코드를 가져옵니다.

쿼리 매개변수

파라미터	유형	필수의	설명
`domain`	string	아니요	정확히 이 도메인 이름을 가진 영역만 반환
`page`	integer	아니요	1부터 시작하는 페이지 번호

예시 요청

cURL

Python

JavaScript

curl -X GET "https://admin.vps.org/api/v1/dns-zones/?domain=example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

import requests

url = "https://admin.vps.org/api/v1/dns-zones/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers, params={"domain": "example.com"})
for zone in response.json()["results"]:
    print(zone["uuid"], zone["domain"], zone["record_count"])

const response = await fetch('https://admin.vps.org/api/v1/dns-zones/?domain=example.com', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});

const data = await response.json();
console.log(data.results);

예시 답변

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c",
      "domain": "example.com",
      "created_at": "2026-09-06T03:11:48.829693Z",
      "record_count": 5
    }
  ]
}

응답 필드

필드	유형	설명
`uuid`	string	영역 식별자
`domain`	string	도메인 이름, 소문자로 저장
`created_at`	datetime	생성 시간 (ISO 8601, UTC)
`record_count`	integer	NS 레코드 3개를 포함한 영역의 레코드 수

응답 상태 코드

200	성공
403	API 토큰이 누락되었거나 잘못되었거나 토큰에 필요한 권한이 없습니다.

메시지 /api/v1/dns-zones/

DNS 영역 만들기

구역을 생성하고 게시합니다. 구역은 ns1, ns2 및 ns3.vps.org에 대한 세 개의 NS 레코드로 시작되며, 이 레코드는 시스템 레코드이므로 편집하거나 삭제할 수 없습니다.

요청 본문 매개변수

파라미터	유형	필수의	설명
`domain`	string	예	도메인 이름, 예를 들어 example.com

curl -X POST "https://admin.vps.org/api/v1/dns-zones/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

예시 답변

{
  "uuid": "c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c",
  "domain": "example.com",
  "created_at": "2026-09-14T21:02:11.402113Z",
  "records": [
    {
      "uuid": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
      "record_type": "NS",
      "name": "@",
      "value": "ns1.vps.org",
      "ttl": 86400,
      "priority": null,
      "created_at": "2026-09-14"
    },
    ...
  ],
  "record_count": 3
}

응답 상태 코드

201	영역 생성됨
400	도메인 이름 찾기

얻다 /api/v1/dns-zones/{uuid}/

DNS 영역 세부 정보 가져오기

레코드 배열에 있는 모든 레코드를 포함한 한 영역을 반환합니다. 응답은 위의 create 응답과 동일한 형태를 갖습니다.

curl -X GET "https://admin.vps.org/api/v1/dns-zones/c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

응답 상태 코드

200	성공
404	찾을 수 없거나 다른 계정에 속합니다.

삭제 /api/v1/dns-zones/{uuid}/

DNS 영역 삭제

세 개의 네임서버 모두에서 구역을 제거하고, 아무 네임서버도 구역을 서비스하지 않는지 확인한 다음 구역과 그 레코드를 삭제합니다. 네임서버가 아직 구역에 대해 응답하지 않으면 요청이 실패하고 구역이 유지되어 다시 시도할 수 있습니다.

curl -X DELETE "https://admin.vps.org/api/v1/dns-zones/c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

응답 상태 코드

204	삭제됨. 응답에는 본문이 없습니다.
400	네임서버가 여전히 영역에 서비스를 제공합니다. 영역이 삭제되지 않았습니다. 세부 정보 필드에 오류가 나열되어 있습니다.
404	찾을 수 없거나 다른 계정에 속합니다.

얻다 메시지 /api/v1/dns-zones/{uuid}/records/

영역에 레코드 목록 또는 추가

GET은 종류와 이름에 따라 정렬된 플레인 어레이(페이지화되지 않음)로서 존의 모든 레코드를 반환한다. POST는 레코드를 존에 추가하고 퍼블리싱한다.

요청 본문 매개변수 (POST)

파라미터	유형	필수의	설명
`record_type`	string	예	A, AAAA, CNAME, MX, NS, TXT, SRV, PTR, SOA, CAA
`name`	string	예	도메인 자체에 대한 @ 또는 www와 같은 레이블. 이름은 소문자로 저장됩니다.
`value`	string	예	IP 주소나 호스트 이름과 같은 레코드 데이터. 호스트 이름은 끝에 점이 필요하지 않으며 TXT 값은 따옴표가 필요하지 않습니다. 둘 다 레코드가 게시될 때 추가됩니다.
`ttl`	integer	예	초 단위로 살 수 있는 시간
`priority`	integer	MX 및 SRV만 사용	MX 및 SRV 레코드에 필요하며 다른 모든 유형에 대해서는 무시됩니다. SRV의 경우 weight, port 및 target 값을 입력합니다.

예시 요청

cURL

Python

curl -X POST "https://admin.vps.org/api/v1/dns-zones/c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c/records/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"record_type": "MX", "name": "@", "value": "mail.example.com", "ttl": 3600, "priority": 10}'

import requests

zone_uuid = "c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c"
url = f"https://admin.vps.org/api/v1/dns-zones/{zone_uuid}/records/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
data = {"record_type": "A", "name": "www", "value": "203.0.113.10", "ttl": 3600}

response = requests.post(url, headers=headers, json=data)
print(response.status_code, response.json())

예시 답변

{
  "uuid": "9d430082-5562-42b4-a0b2-12a6f6c862f9",
  "record_type": "MX",
  "name": "@",
  "value": "mail.example.com",
  "ttl": 3600,
  "priority": 10,
  "created_at": "2026-09-14"
}

응답 필드

필드	유형	설명
`uuid`	string	/api/v1/dns-records/ 엔드포인트에서 사용하는 레코드 식별자
`priority`	integer \| null	MX 및 SRV 레코드에 대한 우선순위, 그렇지 않으면 null
`created_at`	date	시간 없이 생성 날짜만 (Y-MM-DD)

응답 상태 코드

200	GET: 영역의 기록
201	POST: 레코드 생성됨
400	알 수 없는 레코드 유형, 누락된 ttl, 우선 순위가 없는 MX 또는 SRV 레코드와 같은 검증 오류
404	찾을 수 없거나 다른 계정에 속합니다.

메시지 /api/v1/dns-zones/{uuid}/sync/

영역 재게시

레코드 변경 사항은 자동으로 게시되지만 게시는 최선의 노력이며 실패는 원래 요청에 실패하지 않습니다. 따라서 변경 사항이 DNS 검색에서 나타나지 않을 때 이것을 사용합니다. 요청 본문이 필요하지 않습니다.

curl -X POST "https://admin.vps.org/api/v1/dns-zones/c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c/sync/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "detail": "Zone example.com synced to PowerDNS"
}

얻다 메시지 /api/v1/dns-records/

영역 전체에서 레코드 목록 또는 생성

GET은 페이지당 25개의 모든 영역의 레코드를 도메인, 유형, 이름에 따라 정렬하여 반환합니다. POST는 영역 레코드 엔드포인트와 같은 레코드를 생성하지만 본문의 영역을 zone_uuid로 받습니다.

쿼리 매개변수

파라미터	유형	필수의	설명
`zone`	string	아니요	이 uuid를 가진 영역의 레코드만
`record_type`	string	아니요	이 유형의 레코드만, 예를 들어 MX (대소문자 구분 안함)
`page`	integer	아니요	1부터 시작하는 페이지 번호

curl -X GET "https://admin.vps.org/api/v1/dns-records/?zone=c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c&record_type=A" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

curl -X POST "https://admin.vps.org/api/v1/dns-records/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zone_uuid": "c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c", "record_type": "TXT", "name": "@", "value": "v=spf1 mx -all", "ttl": 3600}'

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "4b8e2c10-7d3f-4a5b-9e6c-1a2b3c4d5e6f",
      "record_type": "A",
      "name": "www",
      "value": "203.0.113.10",
      "ttl": 3600,
      "priority": null,
      "created_at": "2026-09-14"
    }
  ]
}

응답 상태 코드

200	GET: 성공
201	POST: 레코드 생성됨
400	검증 오류, 또는 zone_uuid가 누락되거나 영역 중 하나가 아닙니다

얻다 PUT PATCH 삭제 /api/v1/dns-records/{uuid}/

레코드 가져오기, 업데이트 또는 삭제

GET은 레코드 하나를 반환합니다. PUT은 이를 교체하며 record_type, name, value, ttl이 필요합니다. PATCH는 보낸 필드만 변경합니다. DELETE는 레코드를 삭제하고 본문 없이 204를 반환합니다. 변경 사항은 즉시 반영됩니다. 존 생성 시 함께 만들어진 NS 레코드는 시스템 레코드이므로, 이를 수정하거나 삭제하려고 하면 403이 반환됩니다.

MX 또는 SRV 레코드의 우선순위를 PATCH할 때, 동일한 요청에서 record_type 를 보냅니다. priority 가 있지만 record_type 이 없는 PATCH 본문은 우선순위를 삭제합니다.

curl -X PATCH "https://admin.vps.org/api/v1/dns-records/4b8e2c10-7d3f-4a5b-9e6c-1a2b3c4d5e6f/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttl": 300}'

응답 상태 코드

200	GET, PUT 또는 PATCH: 기록
204	삭제됨. 응답에는 본문이 없습니다.
400	검증 오류
403	레코드가 시스템 레코드이거나 토큰에 필요한 권한이 없습니다.
404	찾을 수 없거나 다른 계정에 속합니다.

오류 처리

검증 오류는 필드 이름으로 키된 문제를 반환하는 400:

{
  "priority": ["MX records require a priority value"]
}

DNS 변경 테스트

레지스트라 위임 또는 리솔버 캐시가 뒤따르기 전에 변경 사항이 실행되었는지 확인하려면 VPS.org 네임서버를 직접 쿼리합니다.

dig @ns1.vps.org example.com A
dig @ns2.vps.org example.com MX
dig @ns3.vps.org www.example.com

VPS.org API

개요

모든 DNS 영역 나열

쿼리 매개변수

예시 요청

예시 답변

응답 필드

응답 상태 코드

DNS 영역 만들기

요청 본문 매개변수

예시 답변

응답 상태 코드

DNS 영역 세부 정보 가져오기

응답 상태 코드

DNS 영역 삭제

응답 상태 코드

영역에 레코드 목록 또는 추가

요청 본문 매개변수 (POST)

예시 요청

예시 답변

응답 필드

응답 상태 코드

영역 재게시

영역 전체에서 레코드 목록 또는 생성

쿼리 매개변수

응답 상태 코드

레코드 가져오기, 업데이트 또는 삭제

응답 상태 코드

오류 처리

DNS 변경 테스트