DNS Records API

The DNS Records API allows you to manage DNS records for domains in your account.

Get DNS Records

Retrieves all DNS records for a specific domain.

Endpoint: GET /api/v1/domains/{domain_id}/dns

Request

http

GET /api/v1/domains/dom_abc123/dns
Authorization: Bearer YOUR_API_KEY

Response

json

{
  "records": [
    {
      "id": "rec_xyz789",
      "type": "A",
      "name": "@",
      "content": "192.0.2.1",
      "ttl": 300,
      "priority": null,
      "created_at": "2025-01-01T01:00:00Z",
      "updated_at": "2025-01-01T01:00:00Z"
    },
    {
      "id": "rec_abc456",
      "type": "MX",
      "name": "@",
      "content": "mail.example.com",
      "ttl": 3600,
      "priority": 10,
      "created_at": "2025-01-01T01:00:00Z",
      "updated_at": "2025-01-01T01:00:00Z"
    }
  ],
  "total": 2
}

DNS Record Object Fields

Field	Type	Description
`id`	string	Unique record identifier
`type`	string	DNS record type (A, AAAA, CNAME, MX, TXT, SRV, NS)
`name`	string	Record name/subdomain (@ for root domain)
`content`	string	Record value/target
`ttl`	integer	Time to live in seconds
`priority`	integer	Priority (for MX and SRV records only)
`created_at`	string	ISO 8601 timestamp of creation
`updated_at`	string	ISO 8601 timestamp of last update

Examples

javascript

const getDNSRecords = async (domainId) => {
  const response = await fetch(
    `https://api.pocketdns.com/api/v1/domains/${domainId}/dns`,
    {
      headers: {
        'Authorization': 'Bearer sk_live_...'
      }
    }
  );

  const { records } = await response.json();
  return records;
};

const records = await getDNSRecords('dom_abc123');
console.log(`Domain has ${records.length} DNS records`);

Create DNS Record

Creates a new DNS record for a domain.

Endpoint: POST /api/v1/domains/{domain_id}/dns

Request

http

POST /api/v1/domains/dom_abc123/dns
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "type": "A",
  "name": "www",
  "content": "192.0.2.1",
  "ttl": 300
}

Parameters

Parameter	Type	Required	Description
`type`	string	Yes	Record type (A, AAAA, CNAME, MX, TXT, SRV, NS)
`name`	string	Yes	Record name (use "@" for root domain)
`content`	string	Yes	Record value
`ttl`	integer	No	Time to live (default: 300)
`priority`	integer	No	Priority for MX/SRV records

Response

json

{
  "id": "rec_new123",
  "type": "A",
  "name": "www",
  "content": "192.0.2.1",
  "ttl": 300,
  "priority": null,
  "created_at": "2025-01-06T12:30:00Z",
  "updated_at": "2025-01-06T12:30:00Z"
}

Examples

Create A Record

javascript

const createDNSRecord = async (domainId, record) => {
  const response = await fetch(
    `https://api.pocketdns.com/api/v1/domains/${domainId}/dns`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(record)
    }
  );

  return await response.json();
};

// Create A record
const aRecord = await createDNSRecord('dom_abc123', {
  type: 'A',
  name: 'www',
  content: '192.0.2.1',
  ttl: 300
});

Create MX Record

javascript

// Create MX record
const mxRecord = await createDNSRecord('dom_abc123', {
  type: 'MX',
  name: '@',
  content: 'mail.example.com',
  ttl: 3600,
  priority: 10
});

Create CNAME Record

javascript

// Create CNAME record
const cnameRecord = await createDNSRecord('dom_abc123', {
  type: 'CNAME',
  name: 'blog',
  content: 'example.com',
  ttl: 300
});

Update DNS Record

Updates an existing DNS record.

Endpoint: PUT /api/v1/domains/{domain_id}/dns/{record_id}

Request

http

PUT /api/v1/domains/dom_abc123/dns/rec_xyz789
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "content": "192.0.2.2",
  "ttl": 600
}

Parameters

All parameters are optional. Only provided fields will be updated.

Parameter	Type	Description
`name`	string	Record name
`content`	string	Record value
`ttl`	integer	Time to live
`priority`	integer	Priority for MX/SRV records

Response

json

{
  "id": "rec_xyz789",
  "type": "A",
  "name": "@",
  "content": "192.0.2.2",
  "ttl": 600,
  "priority": null,
  "created_at": "2025-01-01T01:00:00Z",
  "updated_at": "2025-01-06T12:30:00Z"
}

Examples

javascript

const updateDNSRecord = async (domainId, recordId, updates) => {
  const response = await fetch(
    `https://api.pocketdns.com/api/v1/domains/${domainId}/dns/${recordId}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(updates)
    }
  );

  return await response.json();
};

// Update IP address
const updated = await updateDNSRecord('dom_abc123', 'rec_xyz789', {
  content: '192.0.2.100'
});

Delete DNS Record

Deletes a DNS record.

Endpoint: DELETE /api/v1/domains/{domain_id}/dns/{record_id}

Request

http

DELETE /api/v1/domains/dom_abc123/dns/rec_xyz789
Authorization: Bearer YOUR_API_KEY

Response

http

204 No Content

Examples

javascript

const deleteDNSRecord = async (domainId, recordId) => {
  const response = await fetch(
    `https://api.pocketdns.com/api/v1/domains/${domainId}/dns/${recordId}`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'Bearer sk_live_...'
      }
    }
  );

  return response.status === 204;
};

const deleted = await deleteDNSRecord('dom_abc123', 'rec_xyz789');
if (deleted) {
  console.log('DNS record deleted successfully');
}

Bulk Operations

Create Multiple Records

Creates multiple DNS records in a single request.

Endpoint: POST /api/v1/domains/{domain_id}/dns/bulk

Request

http

POST /api/v1/domains/dom_abc123/dns/bulk
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "records": [
    {
      "type": "A",
      "name": "@",
      "content": "192.0.2.1",
      "ttl": 300
    },
    {
      "type": "A",
      "name": "www",
      "content": "192.0.2.1",
      "ttl": 300
    },
    {
      "type": "MX",
      "name": "@",
      "content": "mail.example.com",
      "ttl": 3600,
      "priority": 10
    }
  ]
}

Response

json

{
  "created": [
    {
      "id": "rec_new1",
      "type": "A",
      "name": "@",
      "content": "192.0.2.1",
      "ttl": 300
    },
    {
      "id": "rec_new2",
      "type": "A",
      "name": "www",
      "content": "192.0.2.1",
      "ttl": 300
    }
  ],
  "errors": [
    {
      "record": {
        "type": "MX",
        "name": "@",
        "content": "mail.example.com"
      },
      "error": "Priority is required for MX records"
    }
  ]
}

Examples

javascript

const createBulkDNSRecords = async (domainId, records) => {
  const response = await fetch(
    `https://api.pocketdns.com/api/v1/domains/${domainId}/dns/bulk`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ records })
    }
  );

  return await response.json();
};

// Create website DNS setup
const websiteRecords = [
  { type: 'A', name: '@', content: '192.0.2.1', ttl: 300 },
  { type: 'A', name: 'www', content: '192.0.2.1', ttl: 300 },
  { type: 'MX', name: '@', content: 'mail.example.com', ttl: 3600, priority: 10 }
];

const result = await createBulkDNSRecords('dom_abc123', websiteRecords);
console.log(`Created ${result.created.length} records, ${result.errors.length} errors`);

DNS Templates

Apply DNS Template

Applies a predefined DNS template to a domain.

Endpoint: POST /api/v1/domains/{domain_id}/dns/template

Request

http

POST /api/v1/domains/dom_abc123/dns/template
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "template_id": "tpl_website_basic",
  "variables": {
    "ip_address": "192.0.2.1",
    "mail_server": "mail.example.com"
  }
}

Response

json

{
  "template_id": "tpl_website_basic",
  "records_created": [
    {
      "id": "rec_tpl1",
      "type": "A",
      "name": "@",
      "content": "192.0.2.1"
    },
    {
      "id": "rec_tpl2",
      "type": "A",
      "name": "www",
      "content": "192.0.2.1"
    }
  ]
}

Examples

javascript

const applyDNSTemplate = async (domainId, templateId, variables = {}) => {
  const response = await fetch(
    `https://api.pocketdns.com/api/v1/domains/${domainId}/dns/template`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        template_id: templateId,
        variables
      })
    }
  );

  return await response.json();
};

// Apply website template
const result = await applyDNSTemplate('dom_abc123', 'tpl_website_basic', {
  ip_address: '192.0.2.1'
});

DNS Record Types

A Records

Points a domain to an IPv4 address.

javascript

{
  type: 'A',
  name: '@',           // or subdomain
  content: '192.0.2.1',
  ttl: 300
}

AAAA Records

Points a domain to an IPv6 address.

javascript

{
  type: 'AAAA',
  name: '@',
  content: '2001:db8::1',
  ttl: 300
}

CNAME Records

Creates an alias for another domain.

javascript

{
  type: 'CNAME',
  name: 'www',
  content: 'example.com',
  ttl: 300
}

Note: CNAME records cannot be used for the root domain (@).

MX Records

Specifies mail exchange servers.

javascript

{
  type: 'MX',
  name: '@',
  content: 'mail.example.com',
  ttl: 3600,
  priority: 10         // Required for MX records
}

TXT Records

Stores text information.

javascript

{
  type: 'TXT',
  name: '@',
  content: 'v=spf1 include:_spf.google.com ~all',
  ttl: 300
}

SRV Records

Specifies service locations.

javascript

{
  type: 'SRV',
  name: '_sip._tcp',
  content: '10 60 5060 sip.example.com',  // priority weight port target
  ttl: 300
}

NS Records

Specifies authoritative name servers.

javascript

{
  type: 'NS',
  name: 'subdomain',
  content: 'ns1.example.com',
  ttl: 3600
}

Validation Rules

Record Name Validation

Must be 1-253 characters long
Can contain letters, numbers, hyphens, and dots
Cannot start or end with a hyphen
Use "@" for the root domain

TTL Values

Minimum: 60 seconds
Maximum: 86400 seconds (24 hours)
Recommended: 300 seconds for A/AAAA, 3600 seconds for MX

Content Validation

A records: Valid IPv4 address
AAAA records: Valid IPv6 address
CNAME records: Valid domain name
MX records: Valid domain name
TXT records: Any text (max 255 characters per string)

Common Error Codes

Status Code	Error Code	Description
400	`validation_error`	Invalid record data
401	`unauthorized`	Invalid or missing API key
403	`forbidden`	Access denied to domain
404	`not_found`	Domain or record not found
409	`conflict`	Record already exists or conflicts
422	`unprocessable_entity`	Invalid DNS record format
429	`rate_limit_exceeded`	Too many requests
500	`internal_error`	Server error

Rate Limits

Record retrieval: 1000 requests per minute
Record creation: 300 requests per minute
Record updates: 300 requests per minute
Record deletion: 300 requests per minute
Bulk operations: 60 requests per minute

Best Practices

Use appropriate TTL values (300 for frequent changes, 3600 for stable records)
Validate record data before creating records
Use bulk operations for multiple record changes
Monitor DNS propagation after changes
Keep backup of critical DNS configurations
Use templates for common DNS setups
Test DNS changes in a non-production environment first

DNS Records API ​

Get DNS Records ​

Request ​

Response ​

DNS Record Object Fields ​

Examples ​

Create DNS Record ​

Request ​

Parameters ​

Response ​

Examples ​

Create A Record ​

Create MX Record ​

Create CNAME Record ​

Update DNS Record ​

Request ​

Parameters ​

Response ​

Examples ​

Delete DNS Record ​

Request ​

Response ​

Examples ​

Bulk Operations ​

Create Multiple Records ​

Request ​

Response ​

Examples ​

DNS Templates ​

Apply DNS Template ​

Request ​

Response ​

Examples ​

DNS Record Types ​

A Records ​

AAAA Records ​

CNAME Records ​

MX Records ​

TXT Records ​

SRV Records ​

NS Records ​

Validation Rules ​

Record Name Validation ​

TTL Values ​

Content Validation ​

Common Error Codes ​

Rate Limits ​

Best Practices ​

DNS Records API

Get DNS Records

Request

Response

DNS Record Object Fields

Examples

Create DNS Record

Request

Parameters

Response

Examples

Create A Record

Create MX Record

Create CNAME Record

Update DNS Record

Request

Parameters

Response

Examples

Delete DNS Record

Request

Response

Examples

Bulk Operations

Create Multiple Records

Request

Response

Examples

DNS Templates

Apply DNS Template

Request

Response

Examples

DNS Record Types

A Records

AAAA Records

CNAME Records

MX Records

TXT Records

SRV Records

NS Records

Validation Rules

Record Name Validation

TTL Values

Content Validation

Common Error Codes

Rate Limits

Best Practices