{ "openapi": "3.1.0", "info": { "title": "DNS Check API", "version": "2", "description": "Manage DNS Check's DNS record groups and the DNS records in them, run on-demand checks, and read the events their checks produce.\n\nAuthenticate with an API key from the API Keys page (https://www.dnscheck.co/api-settings), sent as `Authorization: Bearer `. Keys in the query string are refused. A key has Read-only access, which allows only the GET endpoints, or Read and write access, which allows every endpoint.\n\nLists are paginated: while a response's `has_more` is true, pass its `next_cursor` back as `cursor` for the next page. Errors are RFC 9457 Problem Details with a stable `code` (https://www.dnscheck.co/api/errors), except error pages from Cloudflare, which sits in front of DNS Check (https://www.dnscheck.co/api/errors#cloudflare-errors), so check the `Content-Type` before parsing an error as Problem Details.\n\nRequest bodies are JSON objects. PATCH takes only the fields you're changing (JSON merge patch), as `application/json` or `application/merge-patch+json`. Fields and query parameters an endpoint doesn't know are refused, not ignored.\n\nSafe retries: send an `Idempotency-Key` header on a POST, and a retry with the same key gets the first response instead of repeating the write. Every GET response carries an `ETag`: send it as `If-None-Match` to get a 304 while the response is unchanged. A single record group's or DNS record's ETag also works as `If-Match` on a PATCH or DELETE, to refuse the write if someone edited the resource since you read it.\n\nEach account has per-minute budgets shared by all of its keys: one for requests, one for writes (one per DNS record or record group created, changed, or deleted, except as a zone file import's and a record group delete's descriptions say), and one for on-demand checks, plus a daily write quota. They're reported in the `RateLimit` and `RateLimit-Policy` headers of draft-ietf-httpapi-ratelimit-headers-11.\n\nCreating or changing a DNS record queues a check of it right away, in the background, as does an on-demand check that returns 202. To get the result, poll the DNS record until its `checked_at` is later than the one in the response. Nothing is queued by a PATCH that changes nothing, or by a record group write. An on-demand check that returns 200 queues nothing either: its response already holds the latest result.\n\nClients must ignore fields they don't recognize, and handle values they don't recognize in fields such as `type`, `status`, `check_frequency`, and an error's `code`: new fields and values can be added without a version change.\n\nThe example record group (ea883d67-d9f6-45e3-b3a1-844dd1857824), and the DNS records and events in it, can be read without an API key, but never changed.", "termsOfService": "https://www.dnscheck.co/terms", "contact": { "url": "https://www.dnscheck.co/contact" } }, "servers": [ { "url": "https://www.dnscheck.co/api/v2" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "Record Groups", "description": "Sets of DNS records monitored together", "externalDocs": { "url": "https://www.dnscheck.co/api/record-groups" } }, { "name": "DNS Records", "description": "The DNS records a record group monitors, and on-demand checks", "externalDocs": { "url": "https://www.dnscheck.co/api/dns-records" } }, { "name": "Zone Files", "description": "Import and export a record group as a zone file", "externalDocs": { "url": "https://www.dnscheck.co/api/zone-files" } }, { "name": "Events", "description": "Status changes to passing or failing, and the webhooks that deliver them", "externalDocs": { "url": "https://www.dnscheck.co/api/events" } } ], "paths": { "/record-groups": { "get": { "tags": [ "Record Groups" ], "operationId": "listRecordGroups", "summary": "List the account's record groups", "description": "The account's DNS record groups, oldest first.", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/group_status" }, { "$ref": "#/components/parameters/group_name" }, { "$ref": "#/components/parameters/if_none_match" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RecordGroup" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page. Null on the last." }, "has_more": { "type": "boolean", "description": "Whether there's another page. False on the last." } } }, "examples": { "RecordGroupList": { "$ref": "#/components/examples/RecordGroupList" } } } } }, "304": { "description": "Not modified: the ETag sent in If-None-Match is still current" }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `invalid_parameter`: Invalid parameter. `malformed_request`: Malformed request", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Rate limit reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } } }, "post": { "tags": [ "Record Groups" ], "operationId": "createRecordGroup", "summary": "Create a record group", "description": "Creates a DNS record group. Setting `name_servers` or `check_frequency` to anything but its default needs a plan with custom name servers and check frequency.", "parameters": [ { "$ref": "#/components/parameters/idempotency_key" } ], "responses": { "201": { "description": "Created", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Location": { "$ref": "#/components/headers/Location" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordGroup" }, "examples": { "RecordGroupCreated": { "$ref": "#/components/examples/RecordGroupCreated" } } } } }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `malformed_request`: Malformed request. `invalid_parameter`: Invalid parameter", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: API key lacks access. `account_expired`: Account expired. `feature_not_in_plan`: Feature not in plan. `plan_limit_reached`: Plan limit reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_key_in_use`: Idempotency key in use", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "`unsupported_media_type`: Unsupported media type", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed`: Validation failed. `idempotency_key_reused`: Idempotency key reused", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "ValidationFailed": { "$ref": "#/components/examples/ValidationFailed" } } } } }, "429": { "description": "`rate_limited`: Rate limit reached. `daily_quota_exceeded`: Daily write quota reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordGroupCreate" }, "examples": { "mail": { "summary": "A record group for mail DNS records", "value": { "name": "Mail", "description": "MX, SPF, and DKIM records" } }, "custom": { "summary": "Querying your own name servers hourly (paid plans)", "value": { "name": "Internal", "name_servers": [ "ns1.example.com", "192.0.2.53" ], "check_frequency": 3600, "public": false } } } } } } } }, "/record-groups/{record_group_id}": { "get": { "tags": [ "Record Groups" ], "operationId": "getRecordGroup", "summary": "Get a record group", "description": "One DNS record group, with its record counts by status.", "parameters": [ { "$ref": "#/components/parameters/record_group_id" }, { "$ref": "#/components/parameters/if_none_match" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordGroup" }, "examples": { "RecordGroup": { "$ref": "#/components/examples/RecordGroup" } } } } }, "304": { "description": "Not modified: the ETag sent in If-None-Match is still current" }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `invalid_parameter`: Invalid parameter. `malformed_request`: Malformed request", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Not found", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Rate limit reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } }, "security": [ { "bearer": [] }, {} ] }, "patch": { "tags": [ "Record Groups" ], "operationId": "updateRecordGroup", "summary": "Update a record group", "description": "Changes the fields sent, and leaves the rest as they are.", "parameters": [ { "$ref": "#/components/parameters/record_group_id" }, { "$ref": "#/components/parameters/if_match" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordGroup" }, "examples": { "RecordGroup": { "$ref": "#/components/examples/RecordGroup" } } } } }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `malformed_request`: Malformed request. `invalid_parameter`: Invalid parameter", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: API key lacks access. `account_expired`: Account expired. `feature_not_in_plan`: Feature not in plan. `example_group_read_only`: Example group is read-only", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Not found", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "412": { "description": "`precondition_failed`: Precondition failed", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "`unsupported_media_type`: Unsupported media type", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed`: Validation failed", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "ValidationFailed": { "$ref": "#/components/examples/ValidationFailed" } } } } }, "429": { "description": "`rate_limited`: Rate limit reached. `daily_quota_exceeded`: Daily write quota reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordGroupUpdate" }, "examples": { "rename": { "summary": "Rename it", "value": { "name": "Mail servers" } }, "pause": { "summary": "Pause its checks (paid plans)", "value": { "check_frequency": 0 } } } }, "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/RecordGroupUpdate" }, "examples": { "rename": { "summary": "Rename it", "value": { "name": "Mail servers" } }, "pause": { "summary": "Pause its checks (paid plans)", "value": { "check_frequency": 0 } } } } } } }, "delete": { "tags": [ "Record Groups" ], "operationId": "deleteRecordGroup", "summary": "Delete a record group", "description": "Deletes the record group and every DNS record in it. Counts as one write, however many DNS records it holds.", "parameters": [ { "$ref": "#/components/parameters/record_group_id" }, { "$ref": "#/components/parameters/if_match" } ], "responses": { "204": { "description": "Deleted" }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `invalid_parameter`: Invalid parameter. `malformed_request`: Malformed request", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: API key lacks access. `example_group_read_only`: Example group is read-only", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Not found", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "412": { "description": "`precondition_failed`: Precondition failed", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Rate limit reached. `daily_quota_exceeded`: Daily write quota reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } } } }, "/record-groups/{record_group_id}/dns-records": { "get": { "tags": [ "DNS Records" ], "operationId": "listDnsRecords", "summary": "List the DNS records in a record group", "description": "The record group's DNS records, oldest first.", "parameters": [ { "$ref": "#/components/parameters/record_group_id" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/record_type" }, { "$ref": "#/components/parameters/record_status" }, { "$ref": "#/components/parameters/record_name" }, { "$ref": "#/components/parameters/if_none_match" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DnsRecord" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page. Null on the last." }, "has_more": { "type": "boolean", "description": "Whether there's another page. False on the last." } } }, "examples": { "DnsRecordList": { "$ref": "#/components/examples/DnsRecordList" } } } } }, "304": { "description": "Not modified: the ETag sent in If-None-Match is still current" }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `invalid_parameter`: Invalid parameter. `malformed_request`: Malformed request", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Not found", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Rate limit reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } }, "security": [ { "bearer": [] }, {} ] }, "post": { "tags": [ "DNS Records" ], "operationId": "createDnsRecord", "summary": "Add a DNS record to a record group", "description": "Adds a DNS record to monitor. Its status is `unknown` until its first check, which is queued right away.", "parameters": [ { "$ref": "#/components/parameters/record_group_id" }, { "$ref": "#/components/parameters/idempotency_key" } ], "responses": { "201": { "description": "Created", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" }, "Location": { "$ref": "#/components/headers/Location" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsRecordWritten" }, "examples": { "DnsRecordCreated": { "$ref": "#/components/examples/DnsRecordCreated" } } } } }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `malformed_request`: Malformed request. `invalid_parameter`: Invalid parameter", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: API key lacks access. `account_expired`: Account expired. `feature_not_in_plan`: Feature not in plan. `plan_limit_reached`: Plan limit reached. `example_group_read_only`: Example group is read-only", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Not found", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_key_in_use`: Idempotency key in use", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "`unsupported_media_type`: Unsupported media type", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed`: Validation failed. `idempotency_key_reused`: Idempotency key reused", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "ValidationFailed": { "$ref": "#/components/examples/ValidationFailed" } } } } }, "429": { "description": "`rate_limited`: Rate limit reached. `daily_quota_exceeded`: Daily write quota reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsRecordCreate" }, "examples": { "mx": { "summary": "An MX record", "value": { "name": "example.com", "type": "MX", "values": [ "10 mail.example.com." ] } }, "load_balancer": { "summary": "A load balancer A record (paid plans)", "value": { "name": "www.example.com", "type": "A", "values": [ "192.0.2.1", "192.0.2.2" ], "load_balancer": true } } } } } } } }, "/record-groups/{record_group_id}/zone-file": { "get": { "tags": [ "Zone Files" ], "operationId": "getZoneFile", "summary": "Export a record group as a zone file", "description": "The record group's DNS records in zone file syntax, as on its Export page. Records that zone file syntax can't express (load balancer, inverted, wildcard-value, and ALIAS records) are at the end as comments, which DNS servers ignore and a zone file import restores.", "parameters": [ { "$ref": "#/components/parameters/record_group_id" }, { "$ref": "#/components/parameters/if_none_match" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZoneFile" }, "examples": { "ZoneFile": { "$ref": "#/components/examples/ZoneFile" } } } } }, "304": { "description": "Not modified: the ETag sent in If-None-Match is still current" }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `invalid_parameter`: Invalid parameter. `malformed_request`: Malformed request", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Not found", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Rate limit reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } }, "security": [ { "bearer": [] }, {} ] } }, "/record-groups/{record_group_id}/zone-file/import": { "post": { "tags": [ "Zone Files" ], "operationId": "importZoneFile", "summary": "Import a zone file", "description": "Adds a DNS record for each record in the zone file that the record group doesn't already have, as the web interface's import does. Records that can't be imported are skipped and listed in `warnings`, and the import stops at the plan's DNS record limit. With `replace_existing`, the group's DNS records that aren't in the file are deleted. An import whose file matches no DNS records and adds none is refused, even with `replace_existing`. Counts as many writes as the larger of the DNS records it adds and those it deletes, plus those it updates, and a refused import, including one over the write budget, changes nothing. Checks follow as for a single DNS record.", "parameters": [ { "$ref": "#/components/parameters/record_group_id" }, { "$ref": "#/components/parameters/idempotency_key" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZoneFileImport" }, "examples": { "ZoneFileImport": { "$ref": "#/components/examples/ZoneFileImport" } } } } }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `malformed_request`: Malformed request. `invalid_parameter`: Invalid parameter", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: API key lacks access. `account_expired`: Account expired. `plan_limit_reached`: Plan limit reached. `example_group_read_only`: Example group is read-only", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Not found", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_key_in_use`: Idempotency key in use", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "`unsupported_media_type`: Unsupported media type", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`too_many_writes`: Too many writes for one request. `validation_failed`: Validation failed. `idempotency_key_reused`: Idempotency key reused", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "ValidationFailed": { "$ref": "#/components/examples/ValidationFailed" } } } } }, "429": { "description": "`rate_limited`: Rate limit reached. `daily_quota_exceeded`: Daily write quota reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZoneFileImportCreate" }, "examples": { "zone": { "summary": "Import a zone", "value": { "zone_file": "$ORIGIN example.com.\n@ IN MX 10 mail\nmail IN A 192.0.2.25\n" } }, "replace": { "summary": "Make the record group match a zone", "value": { "zone_file": "$ORIGIN example.com.\nwww IN A 192.0.2.1\n", "replace_existing": true } } } } } } } }, "/dns-records": { "get": { "tags": [ "DNS Records" ], "operationId": "listAllDnsRecords", "summary": "List all the account's DNS records", "description": "Every DNS record in the account's record groups, oldest first, with the same filters as a record group's list. To find what's failing, send `status=failing`.", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/record_type" }, { "$ref": "#/components/parameters/record_status" }, { "$ref": "#/components/parameters/record_name" }, { "$ref": "#/components/parameters/if_none_match" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DnsRecord" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page. Null on the last." }, "has_more": { "type": "boolean", "description": "Whether there's another page. False on the last." } } }, "examples": { "DnsRecordList": { "$ref": "#/components/examples/DnsRecordList" } } } } }, "304": { "description": "Not modified: the ETag sent in If-None-Match is still current" }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `invalid_parameter`: Invalid parameter. `malformed_request`: Malformed request", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Rate limit reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } } } }, "/dns-records/{dns_record_id}": { "get": { "tags": [ "DNS Records" ], "operationId": "getDnsRecord", "summary": "Get a DNS record", "description": "One DNS record, including its latest check's status and, if it failed, why.", "parameters": [ { "$ref": "#/components/parameters/dns_record_id" }, { "$ref": "#/components/parameters/if_none_match" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsRecord" }, "examples": { "DnsRecord": { "$ref": "#/components/examples/DnsRecord" } } } } }, "304": { "description": "Not modified: the ETag sent in If-None-Match is still current" }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `invalid_parameter`: Invalid parameter. `malformed_request`: Malformed request", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Not found", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Rate limit reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } }, "security": [ { "bearer": [] }, {} ] }, "patch": { "tags": [ "DNS Records" ], "operationId": "updateDnsRecord", "summary": "Update a DNS record", "description": "Changes the fields sent, and leaves the rest as they are. A changed record is checked right away, in the background. Until then, its `status`, `error`, and `checked_at` are from the last check, of the old value.", "parameters": [ { "$ref": "#/components/parameters/dns_record_id" }, { "$ref": "#/components/parameters/if_match" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsRecordWritten" }, "examples": { "DnsRecordWritten": { "$ref": "#/components/examples/DnsRecordWritten" } } } } }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `malformed_request`: Malformed request. `invalid_parameter`: Invalid parameter", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: API key lacks access. `account_expired`: Account expired. `feature_not_in_plan`: Feature not in plan. `example_group_read_only`: Example group is read-only", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Not found", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "412": { "description": "`precondition_failed`: Precondition failed", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "415": { "description": "`unsupported_media_type`: Unsupported media type", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`validation_failed`: Validation failed", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "examples": { "ValidationFailed": { "$ref": "#/components/examples/ValidationFailed" } } } } }, "429": { "description": "`rate_limited`: Rate limit reached. `daily_quota_exceeded`: Daily write quota reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsRecordUpdate" }, "examples": { "values": { "summary": "Change the expected value", "value": { "values": [ "192.0.2.10" ] } } } }, "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/DnsRecordUpdate" }, "examples": { "values": { "summary": "Change the expected value", "value": { "values": [ "192.0.2.10" ] } } } } } } }, "delete": { "tags": [ "DNS Records" ], "operationId": "deleteDnsRecord", "summary": "Delete a DNS record", "description": "Deletes the DNS record and its events.", "parameters": [ { "$ref": "#/components/parameters/dns_record_id" }, { "$ref": "#/components/parameters/if_match" } ], "responses": { "204": { "description": "Deleted" }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `invalid_parameter`: Invalid parameter. `malformed_request`: Malformed request", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: API key lacks access. `example_group_read_only`: Example group is read-only", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Not found", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "412": { "description": "`precondition_failed`: Precondition failed", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Rate limit reached. `daily_quota_exceeded`: Daily write quota reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } } } }, "/dns-records/{dns_record_id}/check": { "post": { "tags": [ "DNS Records" ], "operationId": "checkDnsRecord", "summary": "Check a DNS record on demand", "description": "Queues a check of the DNS record, usually run within a few seconds, and returns the DNS record as it stands before it. The check's result becomes the record's status, as a scheduled check's would, sending any notifications. To get the result, poll the DNS record until its `checked_at` is later than the one in this response. For an exclusive record, the exclusive records sharing its name and type are checked with it. If another check of the record is running, its result stands in for this one's. If one finished within the last 3 seconds, such as the check after a write, it is the result: nothing is queued or charged, and the response is the DNS record with a 200.", "parameters": [ { "$ref": "#/components/parameters/dns_record_id" }, { "$ref": "#/components/parameters/idempotency_key" } ], "responses": { "202": { "description": "Accepted: queued to run soon", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsRecord" }, "examples": { "CheckQueued": { "$ref": "#/components/examples/CheckQueued" } } } } }, "200": { "description": "Nothing was queued: the result of a check that just finished", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsRecord" }, "examples": { "DnsRecord": { "$ref": "#/components/examples/DnsRecord" } } } } }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `malformed_request`: Malformed request. `invalid_parameter`: Invalid parameter", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "`insufficient_scope`: API key lacks access. `account_expired`: Account expired. `example_group_read_only`: Example group is read-only", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Not found", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "`idempotency_key_in_use`: Idempotency key in use", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "`idempotency_key_reused`: Idempotency key reused", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Rate limit reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } } } }, "/dns-records/{dns_record_id}/events": { "get": { "tags": [ "Events" ], "operationId": "listDnsRecordEvents", "summary": "List a DNS record's events", "description": "The DNS record's passing and failing history, newest first, as far back as the account's plan keeps it: the same events as GET /events.", "parameters": [ { "$ref": "#/components/parameters/dns_record_id" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/if_none_match" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "next_cursor", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page. Null on the last." }, "has_more": { "type": "boolean", "description": "Whether there's another page. False on the last." } } }, "examples": { "EventList": { "$ref": "#/components/examples/EventList" } } } } }, "304": { "description": "Not modified: the ETag sent in If-None-Match is still current" }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `invalid_parameter`: Invalid parameter. `malformed_request`: Malformed request", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "`not_found`: Not found", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Rate limit reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } }, "security": [ { "bearer": [] }, {} ] } }, "/events": { "get": { "tags": [ "Events" ], "operationId": "listEvents", "summary": "Read the account's event feed", "description": "Every DNS record state change on the account, oldest first, each the same object a version 2 webhook envelope delivers. Use it to catch up on events a webhook endpoint missed, or to poll for changes instead of receiving webhooks. Webhooks usually deliver each event within 5 seconds of it happening, so they're the faster choice when timing matters.\n\nStart without a cursor to read from the oldest event the account's plan keeps, or with `since` set to a time, such as when an outage began, to read the events from then on. Either way, the feed can return events you've already processed, so skip IDs you've seen. `next_cursor` is never null: when `has_more` is false you're caught up, so poll again later with the same `next_cursor`.\n\nA check creates an event when it changes a record's state, including a new record's first result. Events that sent no notifications (the record group has notifications off, the first pass of a new record, a ServFail failure held back by the account's delay, or the pass that ends one) have `notified: false`, and webhooks only deliver events with `notified: true`. Events appear in order as soon as they happen, so the cursor never skips one.", "parameters": [ { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" }, { "$ref": "#/components/parameters/since" }, { "$ref": "#/components/parameters/if_none_match" } ], "responses": { "200": { "description": "OK", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "ETag": { "$ref": "#/components/headers/ETag" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventFeed" }, "examples": { "EventFeed": { "$ref": "#/components/examples/EventFeed" } } } } }, "304": { "description": "Not modified: the ETag sent in If-None-Match is still current" }, "400": { "description": "`api_key_in_query`: API key sent in the URL. `invalid_parameter`: Invalid parameter. `malformed_request`: Malformed request", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "`api_key_invalid`: Invalid API key. `api_key_missing`: API key required", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWWAuthenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "`rate_limited`: Rate limit reached", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "$ref": "#/components/responses/UnexpectedProblem" } } } } }, "webhooks": { "dnsRecordFailing": { "post": { "tags": [ "Events" ], "operationId": "dnsRecordFailing", "summary": "dns_record.failing webhook", "description": "Sent to a webhook when a DNS record starts failing, if its record group's notifications are on. Webhooks need an Enterprise plan. This is the Envelope payload format, version 2: the other formats, and version 1, are on the Webhooks page (https://www.dnscheck.co/webhooks). Signed per Standard Webhooks: verify `webhook-signature` before trusting it, and skip a `webhook-id` you've already processed, since a delivery can arrive more than once.", "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The event's ID, the same as the envelope's `id`. The same on every retry.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "When this attempt was sent, in Unix seconds", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "One or more space-separated `v1,` signatures", "schema": { "type": "string" } }, { "name": "X-DNSCheck-Event", "in": "header", "required": true, "description": "The event type", "schema": { "const": "dns_record.failing" } }, { "name": "X-DNSCheck-Test", "in": "header", "required": false, "description": "Sent only on a test event", "schema": { "const": "true" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "properties": { "type": { "const": "dns_record.failing" } } } ] } } } }, "responses": { "2XX": { "description": "Delivered" }, "default": { "description": "A 5xx, 408, 423, 425, or 429 is retried, as is a timeout, for up to 24 hours, honoring Retry-After. Any other response isn't." } } } }, "dnsRecordPassing": { "post": { "tags": [ "Events" ], "operationId": "dnsRecordPassing", "summary": "dns_record.passing webhook", "description": "Sent to a webhook when a DNS record starts passing, if its record group's notifications are on. Webhooks need an Enterprise plan. This is the Envelope payload format, version 2: the other formats, and version 1, are on the Webhooks page (https://www.dnscheck.co/webhooks). Signed per Standard Webhooks: verify `webhook-signature` before trusting it, and skip a `webhook-id` you've already processed, since a delivery can arrive more than once.", "security": [], "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The event's ID, the same as the envelope's `id`. The same on every retry.", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "When this attempt was sent, in Unix seconds", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "One or more space-separated `v1,` signatures", "schema": { "type": "string" } }, { "name": "X-DNSCheck-Event", "in": "header", "required": true, "description": "The event type", "schema": { "const": "dns_record.passing" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "properties": { "type": { "const": "dns_record.passing" } } } ] } } } }, "responses": { "2XX": { "description": "Delivered" }, "default": { "description": "A 5xx, 408, 423, 425, or 429 is retried, as is a timeout, for up to 24 hours, honoring Retry-After. Any other response isn't." } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "An API key from the API Keys page (https://www.dnscheck.co/api-settings)." } }, "parameters": { "record_group_id": { "name": "record_group_id", "in": "path", "required": true, "description": "The record group's ID", "schema": { "type": "string", "format": "uuid" } }, "dns_record_id": { "name": "dns_record_id", "in": "path", "required": true, "description": "The DNS record's ID", "schema": { "type": "string", "format": "uuid" } }, "limit": { "name": "limit", "in": "query", "required": false, "description": "How many to return", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "cursor": { "name": "cursor", "in": "query", "required": false, "description": "A `next_cursor` from an earlier response", "schema": { "type": "string" } }, "since": { "name": "since", "in": "query", "required": false, "description": "Start with the events from this time on, such as when an outage began. Not in the future, or with `cursor`.", "schema": { "type": "string", "format": "date-time" } }, "group_status": { "name": "status", "in": "query", "required": false, "description": "Only record groups with this status. Case is ignored.", "schema": { "type": "string", "enum": [ "passing", "failing", "unknown" ] } }, "group_name": { "name": "name", "in": "query", "required": false, "description": "Only record groups whose name contains this, ignoring case.", "schema": { "type": "string" } }, "record_type": { "name": "type", "in": "query", "required": false, "description": "Only DNS records of this type. Case is ignored.", "schema": { "type": "string", "enum": [ "A", "AAAA", "ALIAS", "CAA", "CNAME", "HTTPS", "MX", "NS", "PTR", "SOA", "SPF", "SRV", "SVCB", "TXT" ] } }, "record_status": { "name": "status", "in": "query", "required": false, "description": "Only DNS records with this status. Case is ignored.", "schema": { "type": "string", "enum": [ "passing", "failing", "unknown" ] } }, "record_name": { "name": "name", "in": "query", "required": false, "description": "Only DNS records whose name contains this, ignoring case and a trailing dot.", "schema": { "type": "string" } }, "idempotency_key": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string, such as a UUID. A retry with the same key within 24 hours gets the first request's response, marked `Idempotent-Replayed: true`, instead of repeating it.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, "if_match": { "name": "If-Match", "in": "header", "required": false, "description": "An ETag from an earlier response. The write is refused with 412 if the resource was edited since; checks don't count.", "schema": { "type": "string" } }, "if_none_match": { "name": "If-None-Match", "in": "header", "required": false, "description": "An ETag from an earlier response. Returns 304, with no body, while the response would be the same.", "schema": { "type": "string" } } }, "responses": { "UnexpectedProblem": { "description": "Errors any request can get. `method_not_allowed`: Method not allowed. `internal_error`: Internal error. `service_unavailable`: Service unavailable", "headers": { "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "Allow": { "$ref": "#/components/headers/Allow" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "headers": { "RateLimit": { "description": "The request budget left this minute, as `\"requests\";r=;t=`, followed by any write or check budget the request spent from.", "schema": { "type": "string" } }, "RateLimitPolicy": { "description": "The account's request budget, as `\"requests\";q=;w=`. Writes and checks add their own budgets to the list: `writes`, `writes-daily`, and `checks`.", "schema": { "type": "string" } }, "ETag": { "description": "Send as `If-None-Match` on a GET to get a 304 while the response is unchanged. A single record group's or DNS record's ETag also works as `If-Match` on a PATCH or DELETE. Opaque: it changes whenever the response does, including when a check changes it.", "schema": { "type": "string" } }, "Location": { "description": "The new resource's API URL", "schema": { "type": "string", "format": "uri" } }, "IdempotentReplayed": { "description": "`true` when this is the stored response to an earlier request with the same `Idempotency-Key`, returned instead of running the request again. Absent otherwise. Some error responses are replayed too, but never a 429 or 5xx: a retry of one runs again.", "schema": { "type": "string", "enum": [ "true" ] } }, "RetryAfter": { "description": "Seconds to wait before retrying", "schema": { "type": "integer" } }, "Allow": { "description": "The methods the endpoint takes, on `method_not_allowed`", "schema": { "type": "string" } }, "WWWAuthenticate": { "description": "`Bearer realm=\"DNS Check API\"`, followed by `, error=\"invalid_token\"` when the request sent a key", "schema": { "type": "string" } } }, "schemas": { "RecordGroup": { "type": "object", "required": [ "id", "object", "name", "description", "name_servers", "check_frequency", "public", "notifications", "status", "records", "created_at", "updated_at", "web_url", "api_url" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "record_group" }, "name": { "type": "string" }, "description": { "type": "string" }, "name_servers": { "type": "array", "items": { "type": "string" }, "description": "Name servers to query. Empty means DNS Check's own." }, "check_frequency": { "type": "integer", "description": "Seconds between checks, currently 300 or 3600, or 0 when paused. More can be added." }, "public": { "type": "boolean", "description": "Whether anyone with the group's URL can view, and check, it" }, "notifications": { "type": "boolean" }, "status": { "type": "string", "description": "`failing` if any record is failing; `passing` if there's at least one record and all are passing; otherwise `unknown`. Statuses can be added, so handle one you don't recognize." }, "records": { "type": "object", "required": [ "total", "passing", "failing", "unknown" ], "properties": { "total": { "type": "integer" }, "passing": { "type": "integer" }, "failing": { "type": "integer" }, "unknown": { "type": "integer" } } }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339, in UTC" }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339, in UTC. Changed only by an edit to the record group itself, not its DNS records." }, "web_url": { "type": "string", "format": "uri", "description": "The record group's web page" }, "api_url": { "type": "string", "format": "uri" } } }, "RecordGroupCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 64, "description": "Letters, numbers, spaces, hyphens, underscores, periods, ampersands, and apostrophes. Unique within the account, ignoring case." }, "description": { "type": [ "string", "null" ], "maxLength": 256, "default": "" }, "name_servers": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 10, "default": [], "description": "Up to 10 name servers to query, one per entry, by name or IP address. Empty uses DNS Check's own. Needs a paid plan." }, "check_frequency": { "type": "integer", "enum": [ 0, 300, 3600 ], "default": 300, "description": "Seconds between scheduled checks, or 0 to pause them. Needs a paid plan." }, "public": { "type": "boolean", "default": true, "description": "Whether anyone with the record group's URL can view it, and check its DNS records" }, "notifications": { "type": "boolean", "default": true, "description": "Whether its DNS records' status changes send notifications" } }, "additionalProperties": false }, "RecordGroupUpdate": { "type": "object", "required": [], "properties": { "name": { "type": "string", "maxLength": 64, "description": "Letters, numbers, spaces, hyphens, underscores, periods, ampersands, and apostrophes. Unique within the account, ignoring case." }, "description": { "type": [ "string", "null" ], "maxLength": 256 }, "name_servers": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 10, "description": "Up to 10 name servers to query, one per entry, by name or IP address. Empty uses DNS Check's own. Needs a paid plan." }, "check_frequency": { "type": "integer", "enum": [ 0, 300, 3600 ], "description": "Seconds between scheduled checks, or 0 to pause them. Needs a paid plan." }, "public": { "type": "boolean", "description": "Whether anyone with the record group's URL can view it, and check its DNS records" }, "notifications": { "type": "boolean", "description": "Whether its DNS records' status changes send notifications" } }, "additionalProperties": false }, "DnsRecord": { "type": "object", "required": [ "id", "object", "record_group_id", "name", "type", "values", "exclusive", "invert", "load_balancer", "status", "fail_count", "error", "checked_at", "created_at", "updated_at", "web_url", "api_url" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "dns_record" }, "record_group_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Fully qualified, with a trailing dot" }, "type": { "type": "string", "description": "The record type, such as A or MX. Types can be added, so handle one you don't recognize." }, "values": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "The expected values: one, or for a load balancer record, several, any of which may be returned. Each is in zone file presentation format, after the name, class, TTL, and type. TXT and SPF values are returned in double quotes, with `\\\"` for a quote in the text and nothing else escaped, and can be sent with or without them. A long one can be sent as several quoted strings, as a zone file splits it, which are joined into one value with nothing between them. A wildcard such as `*` matches any value, and is returned as entered. See https://www.dnscheck.co/dns-record-types.\n\n- A: An IPv4 address, e.g. `192.0.2.1`\n- AAAA: An IPv6 address, in canonical form, e.g. `2001:db8::1`\n- ALIAS: The target record type, then the target name, e.g. `A target.example.com.`\n- CAA: Flag, tag, then the quoted value, e.g. `0 issue \"letsencrypt.org\"`\n- CNAME: The canonical name, e.g. `target.example.com.`\n- HTTPS: Priority, target, then any parameters, e.g. `1 . alpn=h2,h3`\n- MX: Preference, then the mail exchange, e.g. `10 mail.example.com.`\n- NS: The name server, e.g. `ns1.example.com.`\n- PTR: The name the address points to, e.g. `host.example.com.`\n- SOA: Primary name server, responsible mailbox, serial, refresh, retry, expire, and minimum TTL, e.g. `ns1.example.com. hostmaster.example.com. 2026101801 7200 3600 1209600 3600`\n- SPF: The policy text, in double quotes. This is the legacy SPF resource record type. An SPF policy published in a TXT record, as RFC 7208 requires, has type TXT, e.g. `\"v=spf1 include:_spf.example.com ~all\"`\n- SRV: Priority, weight, port, then the target, e.g. `10 5 443 server.example.com.`\n- SVCB: Priority, target, then any parameters, e.g. `1 . alpn=dot port=853`\n- TXT: The text, in double quotes, e.g. `\"google-site-verification=abc123\"`" }, "exclusive": { "type": "boolean", "description": "Whether the records found must match this record's set exactly: the exclusive records in the group sharing its name and type. ALIAS monitors label it \"Require exact match\". See https://www.dnscheck.co/exclusive-dns-record-matching." }, "invert": { "type": "boolean", "description": "Whether the check passes when the value is *not* found" }, "load_balancer": { "type": "boolean", "description": "Whether `values` lists several values, any of which may be returned" }, "status": { "type": "string", "description": "`passing`, `failing`, or `unknown` until the first check. Statuses can be added, so handle one you don't recognize." }, "fail_count": { "type": "integer", "description": "Consecutive failed checks" }, "error": { "type": [ "string", "null" ], "description": "Why the latest check failed. Null if it passed, if the record hasn't been checked, or while check results are briefly unavailable." }, "checked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the record was last checked. Null until its first check, or while check results are briefly unavailable." }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339, in UTC" }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339, in UTC. Changed by an edit, and by a check that changes `status` or `fail_count`." }, "web_url": { "type": "string", "format": "uri", "description": "The DNS record's web page" }, "api_url": { "type": "string", "format": "uri" } } }, "DnsRecordWritten": { "type": "object", "required": [ "id", "object", "record_group_id", "name", "type", "values", "exclusive", "invert", "load_balancer", "status", "fail_count", "error", "checked_at", "created_at", "updated_at", "web_url", "api_url", "warnings" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "dns_record" }, "record_group_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Fully qualified, with a trailing dot" }, "type": { "type": "string", "description": "The record type, such as A or MX. Types can be added, so handle one you don't recognize." }, "values": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "The expected values: one, or for a load balancer record, several, any of which may be returned. Each is in zone file presentation format, after the name, class, TTL, and type. TXT and SPF values are returned in double quotes, with `\\\"` for a quote in the text and nothing else escaped, and can be sent with or without them. A long one can be sent as several quoted strings, as a zone file splits it, which are joined into one value with nothing between them. A wildcard such as `*` matches any value, and is returned as entered. See https://www.dnscheck.co/dns-record-types.\n\n- A: An IPv4 address, e.g. `192.0.2.1`\n- AAAA: An IPv6 address, in canonical form, e.g. `2001:db8::1`\n- ALIAS: The target record type, then the target name, e.g. `A target.example.com.`\n- CAA: Flag, tag, then the quoted value, e.g. `0 issue \"letsencrypt.org\"`\n- CNAME: The canonical name, e.g. `target.example.com.`\n- HTTPS: Priority, target, then any parameters, e.g. `1 . alpn=h2,h3`\n- MX: Preference, then the mail exchange, e.g. `10 mail.example.com.`\n- NS: The name server, e.g. `ns1.example.com.`\n- PTR: The name the address points to, e.g. `host.example.com.`\n- SOA: Primary name server, responsible mailbox, serial, refresh, retry, expire, and minimum TTL, e.g. `ns1.example.com. hostmaster.example.com. 2026101801 7200 3600 1209600 3600`\n- SPF: The policy text, in double quotes. This is the legacy SPF resource record type. An SPF policy published in a TXT record, as RFC 7208 requires, has type TXT, e.g. `\"v=spf1 include:_spf.example.com ~all\"`\n- SRV: Priority, weight, port, then the target, e.g. `10 5 443 server.example.com.`\n- SVCB: Priority, target, then any parameters, e.g. `1 . alpn=dot port=853`\n- TXT: The text, in double quotes, e.g. `\"google-site-verification=abc123\"`" }, "exclusive": { "type": "boolean", "description": "Whether the records found must match this record's set exactly: the exclusive records in the group sharing its name and type. ALIAS monitors label it \"Require exact match\". See https://www.dnscheck.co/exclusive-dns-record-matching." }, "invert": { "type": "boolean", "description": "Whether the check passes when the value is *not* found" }, "load_balancer": { "type": "boolean", "description": "Whether `values` lists several values, any of which may be returned" }, "status": { "type": "string", "description": "`passing`, `failing`, or `unknown` until the first check. Statuses can be added, so handle one you don't recognize." }, "fail_count": { "type": "integer", "description": "Consecutive failed checks" }, "error": { "type": [ "string", "null" ], "description": "Why the latest check failed. Null if it passed, if the record hasn't been checked, or while check results are briefly unavailable." }, "checked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the record was last checked. Null until its first check, or while check results are briefly unavailable." }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339, in UTC" }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339, in UTC. Changed by an edit, and by a check that changes `status` or `fail_count`." }, "web_url": { "type": "string", "format": "uri", "description": "The DNS record's web page" }, "api_url": { "type": "string", "format": "uri" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Things worth knowing that didn't stop the write, such as an identical DNS record already being in the group, or the legacy SPF resource record type" } } }, "DnsRecordCreate": { "type": "object", "required": [ "name", "type", "values" ], "properties": { "name": { "type": "string", "description": "The name to look up. Always absolute, so `@` isn't accepted. A trailing dot is optional. Stored lowercase, in punycode, and for PTR, an IP address becomes its reverse name." }, "type": { "type": "string", "enum": [ "A", "AAAA", "ALIAS", "CAA", "CNAME", "HTTPS", "MX", "NS", "PTR", "SOA", "SPF", "SRV", "SVCB", "TXT" ] }, "values": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "In zone file presentation format, as in DnsRecord's `values`. Exactly one, unless `load_balancer` is true." }, "exclusive": { "type": "boolean", "default": false, "description": "Can't be combined with `invert` or `load_balancer`" }, "invert": { "type": "boolean", "default": false, "description": "Pass when the value is *not* found. Needs a paid plan." }, "load_balancer": { "type": "boolean", "default": false, "description": "Let `values` list several values, any of which may be returned. For A, AAAA, and CNAME records, on a paid plan." } }, "additionalProperties": false }, "DnsRecordUpdate": { "type": "object", "required": [], "properties": { "name": { "type": "string", "description": "The name to look up. Always absolute, so `@` isn't accepted. A trailing dot is optional. Stored lowercase, in punycode, and for PTR, an IP address becomes its reverse name." }, "type": { "type": "string", "enum": [ "A", "AAAA", "ALIAS", "CAA", "CNAME", "HTTPS", "MX", "NS", "PTR", "SOA", "SPF", "SRV", "SVCB", "TXT" ] }, "values": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "In zone file presentation format, as in DnsRecord's `values`. Exactly one, unless `load_balancer` is true." }, "exclusive": { "type": "boolean", "description": "Can't be combined with `invert` or `load_balancer`" }, "invert": { "type": "boolean", "description": "Pass when the value is *not* found. Needs a paid plan." }, "load_balancer": { "type": "boolean", "description": "Let `values` list several values, any of which may be returned. For A, AAAA, and CNAME records, on a paid plan." } }, "additionalProperties": false }, "ZoneFile": { "type": "object", "required": [ "object", "record_group_id", "forward", "reverse" ], "properties": { "object": { "const": "zone_file" }, "record_group_id": { "type": "string", "format": "uuid" }, "forward": { "type": [ "string", "null" ], "description": "Every DNS record but PTR records in zone file syntax, or null if there are none" }, "reverse": { "type": [ "string", "null" ], "description": "PTR records, which are usually managed elsewhere, in zone file syntax, or null if there are none" } } }, "ZoneFileImportCreate": { "type": "object", "required": [ "zone_file" ], "properties": { "zone_file": { "type": "string", "description": "The zone file's text, up to 100KB. Without an `$ORIGIN`, names are relative to the root." }, "fix_errors": { "type": "boolean", "default": true, "description": "Correct common syntax errors, such as a domain name missing its trailing dot, and detect a missing `$ORIGIN`, as some DNS hosts' exports need" }, "exclusive": { "type": "boolean", "default": false, "description": "Make the imported DNS records exclusive. Inverted and load balancer records are never exclusive." }, "replace_existing": { "type": "boolean", "default": false, "description": "Make the record group match the zone file: delete its DNS records that aren't in the file, and give those that are the `exclusive` setting" } }, "additionalProperties": false }, "ZoneFileImport": { "type": "object", "required": [ "object", "record_group_id", "created", "skipped", "unchanged", "updated", "deleted", "limit_reached", "warnings", "dns_records" ], "properties": { "object": { "const": "zone_file_import" }, "record_group_id": { "type": "string", "format": "uuid" }, "created": { "type": "integer", "description": "DNS records added" }, "skipped": { "type": "integer", "description": "Records that couldn't be imported" }, "unchanged": { "type": "integer", "description": "Records not added because the record group already had them, or because the zone file repeats them" }, "updated": { "type": "integer", "description": "DNS records already in the record group given the `exclusive` setting, with `replace_existing`" }, "deleted": { "type": "integer", "description": "DNS records deleted because they aren't in the zone file, with `replace_existing`" }, "limit_reached": { "type": "boolean", "description": "Whether the import stopped at the plan's DNS record limit" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Why records were skipped, one message each, and why the import stopped early, if it did" }, "dns_records": { "type": "array", "items": { "type": "object", "required": [ "id", "object", "record_group_id", "name", "type", "values", "exclusive", "invert", "load_balancer", "status", "fail_count", "error", "checked_at", "created_at", "updated_at", "web_url", "api_url" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "dns_record" }, "record_group_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Fully qualified, with a trailing dot" }, "type": { "type": "string", "description": "The record type, such as A or MX. Types can be added, so handle one you don't recognize." }, "values": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "The expected values: one, or for a load balancer record, several, any of which may be returned. Each is in zone file presentation format, after the name, class, TTL, and type. TXT and SPF values are returned in double quotes, with `\\\"` for a quote in the text and nothing else escaped, and can be sent with or without them. A long one can be sent as several quoted strings, as a zone file splits it, which are joined into one value with nothing between them. A wildcard such as `*` matches any value, and is returned as entered. See https://www.dnscheck.co/dns-record-types.\n\n- A: An IPv4 address, e.g. `192.0.2.1`\n- AAAA: An IPv6 address, in canonical form, e.g. `2001:db8::1`\n- ALIAS: The target record type, then the target name, e.g. `A target.example.com.`\n- CAA: Flag, tag, then the quoted value, e.g. `0 issue \"letsencrypt.org\"`\n- CNAME: The canonical name, e.g. `target.example.com.`\n- HTTPS: Priority, target, then any parameters, e.g. `1 . alpn=h2,h3`\n- MX: Preference, then the mail exchange, e.g. `10 mail.example.com.`\n- NS: The name server, e.g. `ns1.example.com.`\n- PTR: The name the address points to, e.g. `host.example.com.`\n- SOA: Primary name server, responsible mailbox, serial, refresh, retry, expire, and minimum TTL, e.g. `ns1.example.com. hostmaster.example.com. 2026101801 7200 3600 1209600 3600`\n- SPF: The policy text, in double quotes. This is the legacy SPF resource record type. An SPF policy published in a TXT record, as RFC 7208 requires, has type TXT, e.g. `\"v=spf1 include:_spf.example.com ~all\"`\n- SRV: Priority, weight, port, then the target, e.g. `10 5 443 server.example.com.`\n- SVCB: Priority, target, then any parameters, e.g. `1 . alpn=dot port=853`\n- TXT: The text, in double quotes, e.g. `\"google-site-verification=abc123\"`" }, "exclusive": { "type": "boolean", "description": "Whether the records found must match this record's set exactly: the exclusive records in the group sharing its name and type. ALIAS monitors label it \"Require exact match\". See https://www.dnscheck.co/exclusive-dns-record-matching." }, "invert": { "type": "boolean", "description": "Whether the check passes when the value is *not* found" }, "load_balancer": { "type": "boolean", "description": "Whether `values` lists several values, any of which may be returned" }, "status": { "type": "string", "description": "`passing`, `failing`, or `unknown` until the first check. Statuses can be added, so handle one you don't recognize." }, "fail_count": { "type": "integer", "description": "Consecutive failed checks" }, "error": { "type": [ "string", "null" ], "description": "Why the latest check failed. Null if it passed, if the record hasn't been checked, or while check results are briefly unavailable." }, "checked_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the record was last checked. Null until its first check, or while check results are briefly unavailable." }, "created_at": { "type": "string", "format": "date-time", "description": "RFC 3339, in UTC" }, "updated_at": { "type": "string", "format": "date-time", "description": "RFC 3339, in UTC. Changed by an edit, and by a check that changes `status` or `fail_count`." }, "web_url": { "type": "string", "format": "uri", "description": "The DNS record's web page" }, "api_url": { "type": "string", "format": "uri" } } }, "description": "The DNS records added" } } }, "RecordGroupSummary": { "type": "object", "required": [ "id", "object", "name", "web_url", "api_url" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "record_group" }, "name": { "type": "string" }, "web_url": { "type": "string", "format": "uri", "description": "The record group's web page" }, "api_url": { "type": "string", "format": "uri" } } }, "DnsRecordSummary": { "type": "object", "required": [ "id", "object", "record_group_id", "name", "type", "values", "web_url", "api_url" ], "properties": { "id": { "type": "string", "format": "uuid" }, "object": { "const": "dns_record" }, "record_group_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } }, "web_url": { "type": "string", "format": "uri", "description": "The DNS record's web page" }, "api_url": { "type": "string", "format": "uri" } } }, "Event": { "type": "object", "required": [ "id", "object", "type", "timestamp", "notified", "text", "data" ], "properties": { "id": { "type": "string", "pattern": "^evt_[0-9a-f]{32}$", "description": "Matches the webhook-id of the webhook that delivered it" }, "object": { "const": "event" }, "type": { "type": "string", "description": "`dns_record.failing` or `dns_record.passing`. Event types can be added, so skip one you don't recognize." }, "timestamp": { "type": "string", "format": "date-time", "description": "RFC 3339, in UTC" }, "notified": { "type": [ "boolean", "null" ], "description": "Whether it sent notifications. Null on events from before this was recorded." }, "text": { "type": "string", "description": "A sentence describing the event, linking to the DNS record, as every webhook payload format carries it" }, "data": { "$ref": "#/components/schemas/EventData" } } }, "EventData": { "type": "object", "required": [ "dns_record", "record_group", "status", "error", "responding_name_server", "history_url" ], "properties": { "dns_record": { "$ref": "#/components/schemas/DnsRecordSummary", "description": "The record as it is now: name and values aren't kept per event" }, "record_group": { "$ref": "#/components/schemas/RecordGroupSummary" }, "status": { "type": "string", "description": "The status the record changed to: `passing` or `failing`, matching the event's `type`" }, "error": { "type": [ "string", "null" ], "description": "Why the check failed" }, "responding_name_server": { "type": [ "string", "null" ], "description": "The name server whose answer the check evaluated: its IP address, followed by its hostname in parentheses when it has one" }, "history_url": { "type": "string", "format": "uri", "description": "The record's History page" } } }, "EventFeed": { "type": "object", "required": [ "data", "next_cursor", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "next_cursor": { "type": "string", "description": "Pass as `cursor` to read on. Never null." }, "has_more": { "type": "boolean", "description": "False once you're caught up" } } }, "Problem": { "type": "object", "required": [ "type", "title", "status", "code", "detail" ], "properties": { "type": { "type": "string", "format": "uri", "description": "The error code's documentation page" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string", "description": "Stable: match on this, not on the wording. One of `api_key_in_query`, `invalid_parameter`, `malformed_request`, `api_key_missing`, `api_key_invalid`, `insufficient_scope`, `feature_not_in_plan`, `plan_limit_reached`, `account_expired`, `example_group_read_only`, `not_found`, `method_not_allowed`, `idempotency_key_in_use`, `precondition_failed`, `unsupported_media_type`, `validation_failed`, `idempotency_key_reused`, `too_many_writes`, `rate_limited`, `daily_quota_exceeded`, `internal_error`, `service_unavailable`. Codes can be added, so handle one you don't recognize by its `status`." }, "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "code", "message" ], "properties": { "field": { "type": "string", "description": "The field or parameter. Absent when the error is about the combination of fields." }, "code": { "type": "string", "description": "Stable, as the top-level `code` is. One of `required`, `invalid_type`, `unknown_field`, `unknown_parameter`, `too_short`, `too_long`, `unsupported`, `already_exists`, `no_records`, `nothing_imported`, `invalid`. Codes can be added, so treat one you don't recognize as `invalid`." }, "message": { "type": "string" } } } }, "limit": { "type": "integer", "description": "The plan's limit, on `plan_limit_reached`, `too_many_writes`, `rate_limited`, and `daily_quota_exceeded`" }, "remaining": { "type": "integer", "description": "What's left of the budget, on `rate_limited` and `daily_quota_exceeded`" }, "upgrade_url": { "type": "string", "format": "uri", "description": "Where to compare plans with higher limits" }, "request_id": { "type": "string" } } } }, "examples": { "RecordGroup": { "summary": "The example.com record group, with one DNS record failing", "value": { "id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "object": "record_group", "name": "example.com", "description": "", "name_servers": [], "check_frequency": 300, "public": true, "notifications": true, "status": "failing", "records": { "total": 2, "passing": 1, "failing": 1, "unknown": 0 }, "created_at": "2026-10-20T15:30:00Z", "updated_at": "2026-10-20T15:30:00Z", "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "api_url": "https://www.dnscheck.co/api/v2/record-groups/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40" } }, "RecordGroupList": { "summary": "The account's only record group", "value": { "data": [ { "id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "object": "record_group", "name": "example.com", "description": "", "name_servers": [], "check_frequency": 300, "public": true, "notifications": true, "status": "failing", "records": { "total": 2, "passing": 1, "failing": 1, "unknown": 0 }, "created_at": "2026-10-20T15:30:00Z", "updated_at": "2026-10-20T15:30:00Z", "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "api_url": "https://www.dnscheck.co/api/v2/record-groups/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40" } ], "next_cursor": null, "has_more": false } }, "RecordGroupCreated": { "summary": "A new record group, before any DNS records are added", "value": { "id": "9a2e4c6b-1f3d-4b5a-8e7c-2d4f6a8b0c1e", "object": "record_group", "name": "Mail", "description": "MX, SPF, and DKIM records", "name_servers": [], "check_frequency": 300, "public": true, "notifications": true, "status": "unknown", "records": { "total": 0, "passing": 0, "failing": 0, "unknown": 0 }, "created_at": "2026-11-02T14:30:12Z", "updated_at": "2026-11-02T14:30:12Z", "web_url": "https://www.dnscheck.co/tests/9a2e4c6b-1f3d-4b5a-8e7c-2d4f6a8b0c1e", "api_url": "https://www.dnscheck.co/api/v2/record-groups/9a2e4c6b-1f3d-4b5a-8e7c-2d4f6a8b0c1e" } }, "DnsRecord": { "summary": "A failing A record", "value": { "id": "0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d", "object": "dns_record", "record_group_id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "name": "www.example.com.", "type": "A", "values": [ "192.0.2.1" ], "exclusive": false, "invert": false, "load_balancer": false, "status": "failing", "fail_count": 3, "error": "Expected:\nwww.example.com. A 192.0.2.1\n\nFound:\nwww.example.com. A 192.0.2.10", "checked_at": "2026-11-02T14:05:12Z", "created_at": "2026-10-20T15:30:00Z", "updated_at": "2026-11-02T13:55:12Z", "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2", "api_url": "https://www.dnscheck.co/api/v2/dns-records/0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d" } }, "DnsRecordList": { "summary": "Two DNS records", "value": { "data": [ { "id": "6f1c9e2d-0b8a-4f7e-8d6c-5b4a3f2e1d0c", "object": "dns_record", "record_group_id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "name": "example.com.", "type": "MX", "values": [ "10 mail.example.com." ], "exclusive": false, "invert": false, "load_balancer": false, "status": "passing", "fail_count": 0, "error": null, "checked_at": "2026-11-02T14:05:12Z", "created_at": "2026-10-20T15:30:00Z", "updated_at": "2026-10-20T15:30:04Z", "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/1", "api_url": "https://www.dnscheck.co/api/v2/dns-records/6f1c9e2d-0b8a-4f7e-8d6c-5b4a3f2e1d0c" }, { "id": "0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d", "object": "dns_record", "record_group_id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "name": "www.example.com.", "type": "A", "values": [ "192.0.2.1" ], "exclusive": false, "invert": false, "load_balancer": false, "status": "failing", "fail_count": 3, "error": "Expected:\nwww.example.com. A 192.0.2.1\n\nFound:\nwww.example.com. A 192.0.2.10", "checked_at": "2026-11-02T14:05:12Z", "created_at": "2026-10-20T15:30:00Z", "updated_at": "2026-11-02T13:55:12Z", "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2", "api_url": "https://www.dnscheck.co/api/v2/dns-records/0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d" } ], "next_cursor": null, "has_more": false } }, "DnsRecordWritten": { "summary": "The A record after a PATCH to its value. Its status is from the last check, of the old value, until it's checked again.", "value": { "id": "0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d", "object": "dns_record", "record_group_id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "name": "www.example.com.", "type": "A", "values": [ "192.0.2.10" ], "exclusive": false, "invert": false, "load_balancer": false, "status": "failing", "fail_count": 3, "error": "Expected:\nwww.example.com. A 192.0.2.1\n\nFound:\nwww.example.com. A 192.0.2.10", "checked_at": "2026-11-02T14:05:12Z", "created_at": "2026-10-20T15:30:00Z", "updated_at": "2026-11-02T14:20:31Z", "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2", "api_url": "https://www.dnscheck.co/api/v2/dns-records/0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d", "warnings": [] } }, "DnsRecordCreated": { "summary": "A new MX record, which is unknown until its first check", "value": { "id": "b7e1d3c5-2a4f-4c6e-9b8d-1f3a5c7e9b2d", "object": "dns_record", "record_group_id": "9a2e4c6b-1f3d-4b5a-8e7c-2d4f6a8b0c1e", "name": "example.com.", "type": "MX", "values": [ "10 mail.example.com." ], "exclusive": false, "invert": false, "load_balancer": false, "status": "unknown", "fail_count": 0, "error": null, "checked_at": null, "created_at": "2026-11-02T14:31:40Z", "updated_at": "2026-11-02T14:31:40Z", "web_url": "https://www.dnscheck.co/tests/9a2e4c6b-1f3d-4b5a-8e7c-2d4f6a8b0c1e/3", "api_url": "https://www.dnscheck.co/api/v2/dns-records/b7e1d3c5-2a4f-4c6e-9b8d-1f3a5c7e9b2d", "warnings": [] } }, "CheckQueued": { "summary": "The A record, queued for a check: poll it until its checked_at is later than this one", "value": { "id": "0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d", "object": "dns_record", "record_group_id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "name": "www.example.com.", "type": "A", "values": [ "192.0.2.1" ], "exclusive": false, "invert": false, "load_balancer": false, "status": "failing", "fail_count": 3, "error": "Expected:\nwww.example.com. A 192.0.2.1\n\nFound:\nwww.example.com. A 192.0.2.10", "checked_at": "2026-11-02T14:05:12Z", "created_at": "2026-10-20T15:30:00Z", "updated_at": "2026-11-02T13:55:12Z", "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2", "api_url": "https://www.dnscheck.co/api/v2/dns-records/0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d" } }, "ZoneFile": { "summary": "The record group exported", "value": { "object": "zone_file", "record_group_id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "forward": "www.example.com. A 192.0.2.1\nexample.com. MX 10 mail.example.com.\n", "reverse": null } }, "ZoneFileImport": { "summary": "A two-record zone file imported into an empty record group", "value": { "object": "zone_file_import", "record_group_id": "9a2e4c6b-1f3d-4b5a-8e7c-2d4f6a8b0c1e", "created": 2, "skipped": 0, "unchanged": 0, "updated": 0, "deleted": 0, "limit_reached": false, "warnings": [], "dns_records": [ { "id": "b7e1d3c5-2a4f-4c6e-9b8d-1f3a5c7e9b2d", "object": "dns_record", "record_group_id": "9a2e4c6b-1f3d-4b5a-8e7c-2d4f6a8b0c1e", "name": "example.com.", "type": "MX", "values": [ "10 mail.example.com." ], "exclusive": false, "invert": false, "load_balancer": false, "status": "unknown", "fail_count": 0, "error": null, "checked_at": null, "created_at": "2026-11-02T14:31:40Z", "updated_at": "2026-11-02T14:31:40Z", "web_url": "https://www.dnscheck.co/tests/9a2e4c6b-1f3d-4b5a-8e7c-2d4f6a8b0c1e/3", "api_url": "https://www.dnscheck.co/api/v2/dns-records/b7e1d3c5-2a4f-4c6e-9b8d-1f3a5c7e9b2d" }, { "id": "c4a6e8f0-3b5d-4f7a-8c9e-0b2d4f6a8c1e", "object": "dns_record", "record_group_id": "9a2e4c6b-1f3d-4b5a-8e7c-2d4f6a8b0c1e", "name": "mail.example.com.", "type": "A", "values": [ "192.0.2.25" ], "exclusive": false, "invert": false, "load_balancer": false, "status": "unknown", "fail_count": 0, "error": null, "checked_at": null, "created_at": "2026-11-02T14:31:40Z", "updated_at": "2026-11-02T14:31:40Z", "web_url": "https://www.dnscheck.co/tests/9a2e4c6b-1f3d-4b5a-8e7c-2d4f6a8b0c1e/4", "api_url": "https://www.dnscheck.co/api/v2/dns-records/c4a6e8f0-3b5d-4f7a-8c9e-0b2d4f6a8c1e" } ] } }, "EventList": { "summary": "The A record's events, newest first", "value": { "data": [ { "id": "evt_9d6a094bcd2c466f9c29690b347ca3d4", "object": "event", "type": "dns_record.failing", "timestamp": "2026-11-02T13:55:12Z", "notified": true, "text": "The www.example.com A record in the \"example.com\" record group is failing: https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2", "data": { "dns_record": { "id": "0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d", "object": "dns_record", "record_group_id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "name": "www.example.com.", "type": "A", "values": [ "192.0.2.1" ], "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2", "api_url": "https://www.dnscheck.co/api/v2/dns-records/0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d" }, "record_group": { "id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "object": "record_group", "name": "example.com", "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "api_url": "https://www.dnscheck.co/api/v2/record-groups/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40" }, "status": "failing", "error": "Expected:\nwww.example.com. A 192.0.2.1\n\nFound:\nwww.example.com. A 192.0.2.10", "responding_name_server": "192.0.2.53 (ns1.example.com)", "history_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2/history" } }, { "id": "evt_5c0e8a2f4b6d4e1a9c3f7b5d2e8a0c46", "object": "event", "type": "dns_record.passing", "timestamp": "2026-10-20T15:30:04Z", "notified": false, "text": "The www.example.com A record in the \"example.com\" record group is passing: https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2", "data": { "dns_record": { "id": "0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d", "object": "dns_record", "record_group_id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "name": "www.example.com.", "type": "A", "values": [ "192.0.2.1" ], "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2", "api_url": "https://www.dnscheck.co/api/v2/dns-records/0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d" }, "record_group": { "id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "object": "record_group", "name": "example.com", "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "api_url": "https://www.dnscheck.co/api/v2/record-groups/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40" }, "status": "passing", "error": null, "responding_name_server": "192.0.2.53 (ns1.example.com)", "history_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2/history" } } ], "next_cursor": null, "has_more": false } }, "EventFeed": { "summary": "The account's events, oldest first, all caught up", "value": { "data": [ { "id": "evt_5c0e8a2f4b6d4e1a9c3f7b5d2e8a0c46", "object": "event", "type": "dns_record.passing", "timestamp": "2026-10-20T15:30:04Z", "notified": false, "text": "The www.example.com A record in the \"example.com\" record group is passing: https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2", "data": { "dns_record": { "id": "0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d", "object": "dns_record", "record_group_id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "name": "www.example.com.", "type": "A", "values": [ "192.0.2.1" ], "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2", "api_url": "https://www.dnscheck.co/api/v2/dns-records/0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d" }, "record_group": { "id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "object": "record_group", "name": "example.com", "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "api_url": "https://www.dnscheck.co/api/v2/record-groups/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40" }, "status": "passing", "error": null, "responding_name_server": "192.0.2.53 (ns1.example.com)", "history_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2/history" } }, { "id": "evt_9d6a094bcd2c466f9c29690b347ca3d4", "object": "event", "type": "dns_record.failing", "timestamp": "2026-11-02T13:55:12Z", "notified": true, "text": "The www.example.com A record in the \"example.com\" record group is failing: https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2", "data": { "dns_record": { "id": "0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d", "object": "dns_record", "record_group_id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "name": "www.example.com.", "type": "A", "values": [ "192.0.2.1" ], "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2", "api_url": "https://www.dnscheck.co/api/v2/dns-records/0d3b5a7c-9e1f-4a2b-8c6d-4e5f6a7b8c9d" }, "record_group": { "id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "object": "record_group", "name": "example.com", "web_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40", "api_url": "https://www.dnscheck.co/api/v2/record-groups/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40" }, "status": "failing", "error": "Expected:\nwww.example.com. A 192.0.2.1\n\nFound:\nwww.example.com. A 192.0.2.10", "responding_name_server": "192.0.2.53 (ns1.example.com)", "history_url": "https://www.dnscheck.co/tests/3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40/2/history" } } ], "next_cursor": "6N0EDlubMmKc2GxQYSSTZw", "has_more": false } }, "ValidationFailed": { "summary": "An A record value that isn't an IPv4 address", "value": { "type": "https://www.dnscheck.co/api/errors#validation_failed", "title": "Validation failed", "status": 422, "code": "validation_failed", "detail": "1 field needs attention.", "errors": [ { "field": "values", "code": "invalid", "message": "IP address should be an IPv4 address, or * for any address" } ], "request_id": "5f2d8c1a-7e3b-4a9d-b6c0-8e1f4a2d7c95" } } } }, "externalDocs": { "description": "API v2 documentation", "url": "https://www.dnscheck.co/api" } }