DNSCove JSON API · 12 min read
Getting Started with the DNSCove JSON API: Automating Your Infrastructure
Learn how to wire the DNSCove JSON API into your automation stack — from your first authenticated call to idempotent record management, safe rollbacks, and CI/CD pipelines that don't break DNS.
A direct DNSCove JSON API integration allows engineering teams to provision, update, and audit authoritative DNS records straight from continuous integration pipelines without manual console intervention. By moving away from manual web dashboard updates, teams eliminate deployment bottlenecks and prevent configuration drift across microservices and staging environments.
Manual record updates slow down software releases and create untracked infrastructure changes. Engineering organizations that deploy several times per day need programmatic DNS management to align domain mapping with automated compute lifecycle events. The DNSCove JSON API uses predictable REST-style conventions: zones and record sets exist as addressable resources, request and response payloads use JSON, and all administrative requests authenticate via bearer tokens in standard HTTP headers.
DNSCove does not expose a Route 53 wire-compatible API in v1; you manage DNS through DNSCove's own JSON API, console, and Terraform guides, and migrate off Route 53 with a one-step zone import. Unlike cloud hyperscalers that charge per hosted zone and bill monthly queries, DNSCove uses fixed-cost pricing rather than per-zone or per-query metering. This model changes automation design. Engineers do not need to construct complex batching logic or delay record verifications merely to avoid query-tier penalties. Source: Dnscove source.
This guide provides an end-to-end blueprint for building a robust DNSCove JSON API integration. It covers API token isolation, core zone and record lifecycle calls, idempotent update patterns, CI/CD pipeline placement, common failure conditions, and administrative boundaries.
Before your first call: tokens, scopes, and environment layout
Every programmatic interaction begins with authentication. DNSCove authenticates API requests using static API tokens passed via the standard HTTP Authorization header. Because an API token grants direct modification rights to your authoritative zones, token storage and permission layout must follow strict operational guardrails. Source: Rfc Editor source.
Generate your tokens inside the DNSCove administrative console under team settings. Do not store raw tokens inside version control repositories, Dockerfiles, or unencrypted CI pipeline definitions. Instead, place tokens in a dedicated secrets manager such as HashiCorp Vault, AWS Secrets Manager, or Doppler. Your build or deploy jobs should consume the token at runtime as a masked environment variable (DNSCOVE_API_TOKEN).
HTTP/1.1 Header Structure:
Authorization: Bearer dnc_live_9f83a2e1c4b706d85e2a104c8f
Content-Type: application/json
Accept: application/json
Operational safety requires isolated tokens for each environment. Create separate tokens for local development, ephemeral staging branches, and production pipelines. If a test runner leaks a staging token during a continuous integration debug session, you can revoke that specific credential in the console without interrupting production delivery. Apply least privilege across systems. A deployment pipeline for customer microservices only requires record-modification rights within a specific child subdomain. It must not hold credentials capable of deleting parent production zones.
A minimal authenticated request checking your account identity illustrates the basic transport syntax:
curl -s -X GET "https://api.dnscove.com/v1/account" \
-H "Authorization: Bearer ${DNSCOVE_API_TOKEN}" \
-H "Accept: application/json"
A successful response returns a 200 OK status with account details in a JSON body:
{
"status": "success",
"data": {
"account_id": "acc_6711a0bf",
"name": "Platform Infrastructure",
"email": "sre-core@example.com",
"zone_limit": 50,
"zone_count": 8
}
}
A common failure mode during initial setup is token leakage into developer shell histories or unencrypted provisioning states. When using infrastructure-as-code tools, review the documentation on protecting secrets within state backends to prevent exposing sensitive bearer tokens in shared remote buckets.
Your first DNSCove JSON API integration: zones and records end to end
Configuring records involves a predictable sequence of API calls. You inspect existing zones, register the target zone, insert foundational address mappings, configure apex routing, and verify the resulting state.
The canonical mapping of record types, TTL parameters, and label syntax directly follows RFC 1035. Understanding this standard helps you configure your payload values correctly.
1. Create an authoritative zone
To register a domain under management, send an HTTP POST request to the /zones endpoint. The JSON payload specifies the domain name and an optional comment for operational tracking:
curl -s -X POST "https://api.dnscove.com/v1/zones" \
-H "Authorization: Bearer ${DNSCOVE_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"name": "example-platform.net",
"description": "Production edge ingress zone"
}'
The response confirms creation and returns the system-assigned unique zone identifier:
{
"status": "success",
"data": {
"zone_id": "zone_88192df4",
"name": "example-platform.net",
"status": "pending_delegation",
"created_at": "2026-10-28T14:22:10Z"
}
}
2. Create standard address records
DNS records live under the /zones/{zone_id}/records subresource. When adding standard host records like an A record, supply the record name, type, time-to-live (TTL in seconds), and an array of target IP addresses:
curl -s -X POST "https://api.dnscove.com/v1/zones/zone_88192df4/records" \
-H "Authorization: Bearer ${DNSCOVE_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"name": "api.example-platform.net",
"type": "A",
"ttl": 300,
"records": [
"198.51.100.45",
"198.51.100.46"
]
}'
Every record payload requires a records JSON array, even when providing a single IP address. This array design allows the DNSCove JSON API integration to handle multi-value round-robin configurations cleanly without changing payload shapes between single-host and multi-host architectures.
3. Handle the zone apex with ALIAS flattening
Traditional DNS standards prohibit placing a CNAME record at the root apex (example-platform.net) because an apex must hold SOA and NS records, and RFC specifications dictate that a CNAME cannot coexist with other record types on the same label. Cloud native platforms typically expose ingress points as dynamic hostnames, such as cloud load balancer hostnames.
DNSCove supports apex ALIAS records (CNAME-at-apex flattening, like Route53 Alias) with serve-stale protection. An ALIAS record accepts a target hostname, dynamically resolves that target to IP addresses on the backend, and presents standard A or AAAA answers to querying resolvers.
To configure an apex alias, supply ALIAS as the record type and point it to your cloud ingress hostname:
curl -s -X POST "https://api.dnscove.com/v1/zones/zone_88192df4/records" \
-H "Authorization: Bearer ${DNSCOVE_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"name": "example-platform.net",
"type": "ALIAS",
"ttl": 60,
"records": [
"ingress-prod-lb-412.elb.us-east-1.amazonaws.com"
]
}'
The serve-stale protection ensures that if the upstream load balancer hostname temporarily fails external resolution checks, authoritative nameservers continue serving the last known valid IP addresses. This avoids service blackouts caused by transient resolver errors. For more details on apex domain architectures, consult our guide on apex ALIAS records and flattening mechanics.
4. Update an existing record in place
Avoid deleting and recreating records when deploying application updates. A delete-and-create sequence causes a temporary resolution gap where authoritative servers return NXDOMAIN to client queries. Use an atomic PUT request targeting the specific record ID to update TTL values and target destinations simultaneously:
curl -s -X PUT "https://api.dnscove.com/v1/zones/zone_88192df4/records/rec_0019bfb2" \
-H "Authorization: Bearer ${DNSCOVE_API_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"name": "api.example-platform.net",
"type": "A",
"ttl": 60,
"records": [
"198.51.100.99"
]
}'
Updating both the TTL and the IP set in a single request ensures atomic updates on authoritative nameservers, protecting resolvers from intermediate half-updated states.
Idempotency and drift: making repeated calls safe
Automated deployment pipelines re-run often. A job may retry after a network timeout, or two concurrent workflow runs might process changes for the same zone. Naive scripts that issue raw POST /records calls fail during re-runs because the target record already exists.
The formal definitions of authoritative data, delegations, and zone operations are outlined in RFC 8499. In operational terms, keeping authoritative state synchronized across automated pipelines requires declarative reconciliation.
+------------------------------------+
| Git Repository (Desired State) |
| records.json / terraform.tfvars |
+-----------------+------------------+
|
v
+-----------------+------------------+
| Reconciliation Worker (CI/CD) |
| 1. GET /zones/{id}/records |
| 2. Calculate Set Difference |
| 3. Apply PUT / POST / DELETE |
+-----------------+------------------+
|
v
+-----------------+------------------+
| DNSCove Authoritative Control |
| Live Zone Records |
+------------------------------------+
A robust automation pipeline uses reconciliation logic structured as follows:
- Retrieve the existing state from the DNSCove JSON API by requesting
GET /zones/{zone_id}/records. - Parse your version-controlled source of truth (such as a declarative YAML or JSON specification stored in Git).
- Compare the live records against the target state by matching record name and record type tuples.
- If the record does not exist on the live zone, issue a
POSTrequest. - If the record exists on the live zone but target values or TTL differ, issue a single
PUTupdate. - If the live record is completely absent from the target specification, mark it for pruning or deletion.
Concurrently executing pipelines introduce read-modify-write hazards. If pipeline A reads a record set, pipeline B modifies it, and pipeline A writes its original payload back, pipeline B's modifications vanish. To detect and prevent this last-writer-wins problem, the API returns an etag header with record representations. When sending updates, pass the retrieved tag in the If-Match request header:
curl -s -X PUT "https://api.dnscove.com/v1/zones/zone_88192df4/records/rec_0019bfb2" \
-H "Authorization: Bearer ${DNSCOVE_API_TOKEN}" \
-H "If-Match: \"7c9b24401a8\"" \
-H "Content-Type: application/json" \
-d '{
"name": "api.example-platform.net",
"type": "A",
"ttl": 300,
"records": ["198.51.100.45"]
}'
If another process altered the record in the interim, the API rejects the update with an HTTP 412 Precondition Failed status code, prompting your pipeline to re-fetch the current state before reapplying changes.
DNSCove does not offer AXFR zone transfer or secondary-DNS operation in v1. Because secondary nameserver sync via AXFR is unavailable, drift detection mechanisms cannot monitor changes through external AXFR pull scripts. Instead, your monitoring systems must query the REST API directly or inspect live responses via standard DNS queries (dig or kdig) directed at ns1.dnscove.com.
Wiring the API into CI/CD and Terraform workflows
Teams integrate programmatic DNS into their release cycles using one of three common patterns: direct API scripting in deployment steps, declarative Infrastructure as Code (IaC) providers, or an internal infrastructure gateway service.
| Integration Model | Implementation Complexity | State Management | Primary Use Case |
|---|---|---|---|
| Direct API Calls (cURL/Python) | Low | Stateless / In-Memory | Ephemeral branch previews and dynamic test environments |
| Terraform Provider | Medium | External State Backend | Production core routing and static infrastructure components |
| Internal Wrapper Service | High | Database / Event Log | Multi-tenant self-service portals with custom approval guardrails |
For teams already managing infrastructure declaratively, using official tooling patterns reduces maintenance burden. Our guide on managing records with Terraform integration patterns outlines how to declare zones and record sets alongside cloud compute resources.
When wiring DNS steps into continuous deployment workflows, operational sequencing is critical:
[ Step 1: Provision Ingress / Load Balancer ]
│
▼
[ Step 2: Validate Target Health & Endpoints ]
│
▼
[ Step 3: Execute DNSCove API Record Update ]
│
▼
[ Step 4: Verify Authoritative Propagation ]
Do not update DNS records before cloud load balancers or container targets pass initial health checks. Pointing live DNS traffic toward an uninitialized backend produces user-facing 502 or connection timeout errors. Maintain a rollback payload in pipeline memory containing the prior record state. If post-deployment smoke tests fail, the workflow can immediately issue a restorative PUT request with previous endpoint values.
Network architecture directly influences TTL selection and rollback velocity. DNSCove runs two unicast authoritative nameservers (ns1 in NYC, ns2 in Frankfurt), not an anycast network. In a dual-node unicast architecture, downstream caching recursive resolvers respect TTL limits consistently across geographic zones. Set low TTL values (such as 30 to 60 seconds) on records subject to active canary updates, and verify that changes propagate to both authoritative nameserver nodes before initiating downstream smoke tests.
Error handling, rate limits, and failure modes worth designing for
Robust automation anticipates edge cases, network partitions, and validation rejections. Standardize your client wrappers to handle common HTTP error categories predictably:
- HTTP 401 Unauthorized: The API token is missing, expired, or revoked. Abort the pipeline immediately. Do not retry automatically, as repeated unauthorized attempts indicate secret misconfiguration.
- HTTP 422 Unprocessable Content: The payload violates DNS syntax standards, such as specifying an invalid IP address format for an A record or exceeding 63 characters on a subdomain label. Log the validation error message and fail the deployment.
- HTTP 409 Conflict: The requested record already exists or the requested modification conflicts with an existing CNAME on the same label. Route these errors through state reconciliation.
- HTTP 429 Too Many Requests: Client requests exceeded per-minute API quotas. Parse the
Retry-Afterresponse header and pause execution. - HTTP 5xx Server Errors or Network Dropouts: Intermittent gateway timeouts or routing interruptions. These requests are safe to retry using an exponential backoff sequence.
Implement an exponential backoff algorithm with jitter when handling transient network issues. Adding randomness (jitter) prevents multiple workers from hammering the API in lockstep:
import time
import random
def execute_with_retry(api_call_func, max_attempts=5):
attempt = 0
base_delay = 1.0 # seconds
max_delay = 30.0
while attempt < max_attempts:
try:
return api_call_func()
except TransientApiException as e:
attempt += 1
if attempt == max_attempts:
raise e
# Full jitter formula
sleep_duration = random.uniform(0, min(max_delay, base_delay * (2 ** attempt)))
time.sleep(sleep_duration)
DNS writes should be the final phase in a deployment workflow, not the initial phase. If an API call fails during an update, your compute nodes remain untouched and live traffic continues hitting the old stable cluster.
DNSCove does not include dedicated DDoS scrubbing in v1. Automation pipelines should not assume the control plane absorbs high-volume query flooding or abusive API calling patterns. Design local automation wrappers to cache read requests, run drift checks on a reasonable schedule (such as hourly instead of every five seconds), and avoid hammering the management API with unnecessary polling cycles.
Sanitize continuous integration output logs. If your automation script dumps the raw request context on error, verify that the Authorization header is redacted before printing to stdout. Leaking tokens into public pipeline logs exposes your DNS zone to unauthorized modifications.
Security and governance for programmatic DNS management
Allowing automated pipelines to write directly to DNS requires clear administrative boundaries and governance controls. An unconstrained token can overwrite critical domain verification records or wipe an entire root zone.
Audit trails and compliance
All operations performed via the DNSCove JSON API generate immutable audit log entries within the platform control plane. Audit events record the token ID, origin IP address, target zone,
- No AWS account required
- Zero-downtime Route 53 cutover
- Apex ALIAS / ANAME to any target
- DNS as code — Terraform, CloudFormation
Straight answer: DNSSEC signing isn't available yet — it's on the roadmap. Everything else here works today. Authoritative nameservers: ns1.dnscove.com, ns2.dnscove.org.