API docs by Redocly

DNSCove control-plane API (1.0)

Download OpenAPI specification:

JSON API for the DNSCove control-plane: magic-link auth, zones and records, delegation/parity checks, snapshot publish, Route53 import, and scoped machine tokens for automation (ACME DNS-01, per-zone record management, and tenant-wide provisioning).

Two credential types, both sent as Authorization: Bearer <token>:

  • Session — a short-lived HMAC token from the magic-link exchange. Full access to the tenant's zones. Used by the console.

  • Scoped machine token (dnsc_<id>_<secret>) — carries one scope:

    • acme-dns01 — bound to one zone; may call only POST /api/zones/{id}/acme-challenge on that zone.
    • zone-admin — bound to one zone; full record CRUD + delegation/parity + ACME on that zone. No zone lifecycle, no publish, no token minting.
    • tenant-admin — tenant-wide (no zone binding): create/list/delete zones, act on any zone, publish, and mint/revoke tokens. Root-equivalent — prefer a narrower scope when one zone is enough.

    An endpoint that doesn't accept a token's scope answers 403.

Infrastructure-as-code: manage zones and records from your existing tooling — see the Terraform / OpenTofu and CloudFormation guides.

auth

Request a magic-link sign-in token

Request Body schema: application/json
required
email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "sent": true,
  • "dev_token": "string",
  • "dev_link": "string"
}

Exchange a magic-link token for a session

Request Body schema: application/json
required
token
required
string

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "token": "string"
}

zones

List zones

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "zones": [
    ]
}

Create a zone

Authorizations:
bearerAuth
Request Body schema: application/json
required
origin
required
string

Responses

Request samples

Content type
application/json
{
  • "origin": "example.com"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "origin": "string",
  • "status": "PENDING_VERIFICATION",
  • "ns": [
    ],
  • "serial": 0,
  • "published_serial": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Get a zone

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: Z1a2b3c4d5e6f70

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenant_id": "string",
  • "origin": "string",
  • "status": "PENDING_VERIFICATION",
  • "ns": [
    ],
  • "serial": 0,
  • "published_serial": 0,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Delete a zone

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: Z1a2b3c4d5e6f70

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Check parent NS delegation (activates the zone when delegated)

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: Z1a2b3c4d5e6f70

Responses

Response samples

Content type
application/json
{
  • "delegation": {
    },
  • "status": "PENDING_VERIFICATION"
}

Compare served records against public DNS ("safe to delete the old zone")

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: Z1a2b3c4d5e6f70

Responses

Response samples

Content type
application/json
{
  • "parity": {
    },
  • "safe_to_delete": true,
  • "status": "PENDING_VERIFICATION"
}

records

List record sets

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: Z1a2b3c4d5e6f70

Responses

Response samples

Content type
application/json
{
  • "rrsets": [
    ]
}

Upsert or delete a record set

Session, zone-admin (this zone), or tenant-admin.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: Z1a2b3c4d5e6f70
Request Body schema: application/json
required
action
string
Default: "UPSERT"
Enum: "UPSERT" "DELETE"
name
required
string
type
required
string
ttl
integer
Default: 300
records
Array of strings

Responses

Request samples

Content type
application/json
{
  • "action": "UPSERT",
  • "name": "www.example.com.",
  • "type": "A",
  • "ttl": 300,
  • "records": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "PENDING",
  • "serial": 0
}

tokens

List a zone's tokens (session or tenant-admin; never returns secrets)

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: Z1a2b3c4d5e6f70

Responses

Response samples

Content type
application/json
{
  • "tokens": [
    ]
}

Mint a per-zone token (session or tenant-admin)

Mints an acme-dns01 or zone-admin token bound to this zone. Returns the plaintext token exactly once — store it securely; it is unrecoverable afterward. tenant-admin is not a per-zone scope; mint it at POST /api/tokens.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: Z1a2b3c4d5e6f70
Request Body schema: application/json
name
string
scope
string
Default: "acme-dns01"
Enum: "acme-dns01" "zone-admin"
expires_in_days
integer

0 = no expiry

Responses

Request samples

Content type
application/json
{
  • "name": "cert-manager webhook",
  • "scope": "acme-dns01",
  • "expires_in_days": 0
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "zone_id": "string",
  • "scope": "acme-dns01",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "revoked": true,
  • "token": "dnsc_1a2b3c4d5e6f7a8b_…"
}

Revoke a per-zone token (session or tenant-admin)

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: Z1a2b3c4d5e6f70
tid
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

List every token in the tenant (session or tenant-admin; no secrets)

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "tokens": [
    ]
}

Mint a token of any scope (session or tenant-admin)

Mints tenant-admin (default, tenant-wide) or a zone-bound scope when a zone_id in the caller's tenant is supplied. Returns the plaintext token exactly once.

Authorizations:
bearerAuth
Request Body schema: application/json
name
string
scope
string
Default: "tenant-admin"
Enum: "tenant-admin" "zone-admin" "acme-dns01"
zone_id
string

required for zone-bound scopes; ignored for tenant-admin

expires_in_days
integer

0 = no expiry

Responses

Request samples

Content type
application/json
{
  • "name": "terraform",
  • "scope": "tenant-admin",
  • "zone_id": "string",
  • "expires_in_days": 0
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "zone_id": "string",
  • "scope": "acme-dns01",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "revoked": true,
  • "token": "dnsc_1a2b3c4d5e6f7a8b_…"
}

Revoke any token in the tenant by id (session or tenant-admin)

Authorizations:
bearerAuth
path Parameters
tid
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

acme

Present or clean up an ACME DNS-01 challenge TXT

Adds (PRESENT) or removes (CLEANUP) one value on the _acme-challenge TXT record and republishes to the edge. Accepts a session or an acme-dns01 / zone-admin token bound to this zone, or a tenant-admin token. Values merge, so multiple challenges at the same name (SAN/wildcard) coexist.

Authorizations:
bearerAuthscopedToken
path Parameters
id
required
string
Example: Z1a2b3c4d5e6f70
Request Body schema: application/json
required
action
required
string
Enum: "PRESENT" "CLEANUP"
name
required
string
value
required
string

base64url key authorization

Responses

Request samples

Content type
application/json
{
  • "action": "PRESENT",
  • "name": "_acme-challenge.canary.lab.dnscove.com.",
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "status": "ok",
  • "action": "string",
  • "changed": true,
  • "published": true,
  • "serial": 0
}

ops

Liveness probe

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Compile and ship a full snapshot to every edge node

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "published": true,
  • "zones": 0,
  • "nodes": [
    ]
}

Import a zone from `aws route53 list-resource-record-sets` JSON

Authorizations:
bearerAuth
Request Body schema: application/json
required
json
required
string

raw Route53 JSON

Responses

Request samples

Content type
application/json
{
  • "json": "string"
}

Response samples

Content type
application/json
{
  • "zone": {
    },
  • "imported": 0,
  • "skipped": [
    ],
  • "published": true,
  • "publish_error": "string",
  • "ns": [
    ]
}