API reference

Zones

GET/zonesList zones

Returns all DNS zones accessible to the authenticated identity.

Parameters

Name	Type	Required	Description
`zoneName`query	`string`	-	Exact zone-name filter. Returns { zones: [...] } with just that zone (or an empty list). Single-label-safe, unlike suffix_of. "name" is an accepted alias.
`name`query	`string`	-	Alias for zoneName.
`suffix_of`query	`string`	-	Longest enclosing-zone match for a FQDN (cert / delegation-parent lookup). Returns a single Zone object, or 404 if none. Requires >= 2 labels, so it does NOT match single-label names - use zoneName for those.

curl -X GET https://api.yeil.app/v1/dns/zones \
  -H "Authorization: Bearer $YEIL_API_KEY"

Responses

200Default and with zoneName/name: { zones: [...] }. With suffix_of: a single Zone object.

401Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

429Rate limited

{
  "error": "rate_limited",
  "message": "Too many requests. Please slow down."
}

POST/zonesCreate a zone

Registers a new DNS zone. Returns the zone and a status indicating whether DNSSEC DS delegation or a Handshake claim is required.

Request body

Name	Type	Required	Description
`zoneName`	`string`	required	The zone apex domain name (e.g. example.com).
`owner`	`string`	-	Zone owner. Use "org:<teamId>" to create in a team, or "personal" (the default when omitted) for a personal zone. App-account keys (yk_) MUST set this to "org:<their own teamId>" and that team must match the key's team - app keys cannot create personal zones, and a missing or bare-id owner is rejected with 403 "app can only create zones in its own team". The key also needs manage-zones = write.

curl -X POST https://api.yeil.app/v1/dns/zones \
  -H "Authorization: Bearer $YEIL_API_KEY"

Responses

200On status=done the response carries id + nameservers + ds so a client can wire records/DS in one call (no follow-up GET to recover the id).

401Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

429Rate limited

{
  "error": "rate_limited",
  "message": "Too many requests. Please slow down."
}

GET/zones/{id}Get a zone

Single-zone detail plus delegation info (nameservers + DS).

Parameters

Name	Type	Required	Description
`id`path	`string`	required	Zone ID.

curl -X GET https://api.yeil.app/v1/dns/zones/$ZONE_ID \
  -H "Authorization: Bearer $YEIL_API_KEY"

Responses

200OK

401Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

404Zone not found.

DELETE/zones/{id}Delete a zone

Permanently deletes a DNS zone and all its records.

Parameters

Name	Type	Required	Description
`id`path	`string`	required	Zone ID.

curl -X DELETE https://api.yeil.app/v1/dns/zones/$ZONE_ID \
  -H "Authorization: Bearer $YEIL_API_KEY"

Responses

204No content

401Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

429Rate limited

{
  "error": "rate_limited",
  "message": "Too many requests. Please slow down."
}

POST/zones/{id}/parkPark a zone

Marks a zone as parked, suspending record resolution.

Parameters

Name	Type	Required	Description
`id`path	`string`	required	Zone ID.

curl -X POST https://api.yeil.app/v1/dns/zones/$ZONE_ID/park \
  -H "Authorization: Bearer $YEIL_API_KEY"

Responses

200OK

401Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

POST/zones/{id}/unparkUnpark a zone

Restores a parked zone to active resolution.

Parameters

Name	Type	Required	Description
`id`path	`string`	required	Zone ID.

curl -X POST https://api.yeil.app/v1/dns/zones/$ZONE_ID/unpark \
  -H "Authorization: Bearer $YEIL_API_KEY"

Responses

200OK

401Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

GET/zones/{id}/dsGet DNSSEC DS record

Returns the DS record for the zone's DNSSEC key, for submission to the parent zone.

Parameters

Name	Type	Required	Description
`id`path	`string`	required	Zone ID.

curl -X GET https://api.yeil.app/v1/dns/zones/$ZONE_ID/ds \
  -H "Authorization: Bearer $YEIL_API_KEY"

Responses

200OK

401Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

Records

GET/zones/{id}/recordsList records

Returns all DNS records in a zone.

Parameters

Name	Type	Required	Description
`id`path	`string`	required	Zone ID.

curl -X GET https://api.yeil.app/v1/dns/zones/$ZONE_ID/records \
  -H "Authorization: Bearer $YEIL_API_KEY"

Responses

200OK

401Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

429Rate limited

{
  "error": "rate_limited",
  "message": "Too many requests. Please slow down."
}

POST/zones/{id}/recordsCreate a record

Adds a new DNS record to a zone.

Parameters

Name	Type	Required	Description
`id`path	`string`	required	Zone ID.

Request body

Name	Type	Required	Description
`name`	`string`	required	Relative to the zone; @ = apex.
`type`	`A \| AAAA \| ALIAS \| CAA \| CNAME \| DS \| HTTPS \| MX \| NS \| PTR \| SRV \| TLSA \| TXT`	required	DNS record type.
`content`	`string`	required	Record value. A, AAAA: an address. CNAME, ALIAS, NS, PTR, MX: a hostname. SRV: "priority weight port target", e.g. "10 5 443 sip.example.com" (target "." means not offered). HTTPS: "priority target params" (RFC 9460), e.g. "1 . alpn=h3,h2" (priority 0 points to another name, target "." means this name). CAA, DS, TLSA, TXT: their usual zone file form.
`ttl`	`integer`	-	Seconds; defaults to the zone default.30–86400
`priority`	`integer`	-	Mail exchange priority.0–65535, MX only

curl -X POST https://api.yeil.app/v1/dns/zones/$ZONE_ID/records \
  -H "Authorization: Bearer $YEIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "_acme-challenge",
  "type": "TXT",
  "content": "u8fGnBm9KvJdLp2eYhRzxQkWAoT7sE0cNiO4M5jHFw",
  "ttl": 120
}'

Responses

201Created

{
  "id": "rec_01HZ7XMGP2Q4V8BNWRKE3DYFT",
  "name": "_acme-challenge",
  "type": "TXT",
  "content": "u8fGnBm9KvJdLp2eYhRzxQkWAoT7sE0cNiO4M5jHFw",
  "ttl": 120,
  "priority": null
}

401Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

429Rate limited

{
  "error": "rate_limited",
  "message": "Too many requests. Please slow down."
}

503The zone is busy with another change. Nothing was written, so the same request can be sent again after Retry-After.
```
{
  "error": "busy",
  "message": "This zone is busy with another change. Try again in a moment."
}
```

PUT/zones/{id}/records/{recordId}Update a record

Replaces a DNS record's content, TTL, or priority.

Parameters

Name	Type	Required	Description
`id`path	`string`	required	Zone ID.
`recordId`path	`string`	required	Record ID.

Request body

Name	Type	Required	Description
`name`	`string`	required	Relative to the zone; @ = apex.
`type`	`A \| AAAA \| ALIAS \| CAA \| CNAME \| DS \| HTTPS \| MX \| NS \| PTR \| SRV \| TLSA \| TXT`	required	DNS record type.
`content`	`string`	required	Record value. A, AAAA: an address. CNAME, ALIAS, NS, PTR, MX: a hostname. SRV: "priority weight port target", e.g. "10 5 443 sip.example.com" (target "." means not offered). HTTPS: "priority target params" (RFC 9460), e.g. "1 . alpn=h3,h2" (priority 0 points to another name, target "." means this name). CAA, DS, TLSA, TXT: their usual zone file form.
`ttl`	`integer`	-	Seconds; defaults to the zone default.30–86400
`priority`	`integer`	-	Mail exchange priority.0–65535, MX only

curl -X PUT https://api.yeil.app/v1/dns/zones/$ZONE_ID/records/$RECORD_ID \
  -H "Authorization: Bearer $YEIL_API_KEY"

Responses

200OK

401Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

429Rate limited

{
  "error": "rate_limited",
  "message": "Too many requests. Please slow down."
}

503The zone is busy with another change. Nothing was written, so the same request can be sent again after Retry-After.
```
{
  "error": "busy",
  "message": "This zone is busy with another change. Try again in a moment."
}
```

DELETE/zones/{id}/records/{recordId}Delete a record

Permanently removes a DNS record from a zone.

Parameters

Name	Type	Required	Description
`id`path	`string`	required	Zone ID.
`recordId`path	`string`	required	Record ID.

curl -X DELETE https://api.yeil.app/v1/dns/zones/$ZONE_ID/records/$RECORD_ID \
  -H "Authorization: Bearer $YEIL_API_KEY"

Responses

204No content

401Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}

429Rate limited

{
  "error": "rate_limited",
  "message": "Too many requests. Please slow down."
}

Record types

Type	Meaning
`A`	Maps a hostname to an IPv4 address.
`AAAA`	Maps a hostname to an IPv6 address.
`ALIAS`	Apex CNAME-like flattening - resolves the target and returns its IPs.
`CAA`	Specifies which certificate authorities may issue TLS certificates.
`CNAME`	Aliases one name to another; not valid at the zone apex.
`DS`	DNSSEC delegation signer record linking a child zone's key.
`HTTPS`	Describes how to reach an HTTPS service: protocols (alpn), port and address hints, or another name to use (RFC 9460).
`MX`	Designates a mail exchanger; uses a priority field (lower = preferred).
`NS`	Delegates a subdomain to a set of authoritative nameservers.
`PTR`	Maps an IP address back to a hostname (reverse DNS); used in in-addr.arpa and ip6.arpa zones.
`SRV`	Locates a service: priority, weight, port and target host, at a name like _sip._tcp.
`TLSA`	DANE certificate association; binds a TLS cert to a DNS name.
`TXT`	Free-form text; used for SPF, DKIM, domain verification, and more.

Error codes

Code	When it occurs
`unauthorized`	Missing or invalid API key.
`bad_request`	Malformed or unparseable request input.
`forbidden`	API key lacks the required permission for this operation.
`no_zone`	Zone not found or does not belong to your account.
`rate_limited`	Too many write requests in a short window.
`conflict`	Duplicate or competing change would violate a constraint.
`dns_server`	Upstream DNS error while applying the change.
`not_found`	Record or other resource does not exist.
`busy`	The zone is busy with another change (503). Nothing was written; retry after Retry-After.
`internal`	Unexpected server error; try again or contact support.

Rate limits

Bucket	Limit	Window
`Zone writes`	10	60 seconds
`Record writes`	60	60 seconds

When a limit is exceeded, the API returns 429 with a Retry-After header indicating how many seconds to wait before retrying.