{ "openapi": "3.1.0", "info": { "title": "OnlyDNS System API", "description": "Manage DNS", "version": "1.0.0", "contact": { "email": "support@onlydns.com", "url": "https://api-docs.onlydns.com/" }, "x-logo": { "url": "https://static.onlydns.com/images/onlydns/logo-stacked.svg", "altText": "OnlyDNS Logo" }, "license": { "name": "MIT", "url": "https://opensource.org/license/mit/" } }, "servers": [ { "url": "https://api.onlydns.com/v1", "description": "Production API" } ], "paths": { "/dns": { "get": { "summary": "List Domains", "description": "List Domains", "operationId": "listDomains", "parameters": [ { "$ref": "#/components/parameters/PaginationOffset" }, { "$ref": "#/components/parameters/PaginationLimit" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDomainListResponse" }, "examples": { "default": { "summary": "List of domains", "value": [ "example.com", "example.net", "example.org", "example.us", "example.eu" ] }, "none": { "summary": "No Domains Found", "value": [] } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "Create DNS Domain", "description": "Create a new DNS domain", "operationId": "createDomain", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DNSDomainCreateRequest" }, "examples": { "general_entry": { "$ref": "#/components/examples/DNSDomainCreateRequestExample" } } } } }, "responses": { "201": { "description": "Success" }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/dns/{domainName}/records": { "parameters": [ { "in": "path", "name": "domainName", "required": true, "schema": { "$ref": "#/components/schemas/DomainName" }, "description": "Domain Name" } ], "get": { "summary": "Get DNS Records", "description": "Get all DNS records for the name", "operationId": "dnsGetRecords", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DNSGetRecordsResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "404": { "description": "Not found" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "summary": "Replace DNS Records", "description": "Replace all DNS records on the Domain", "operationId": "dnsPutRecords", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DNSPutRequest" }, "examples": { "general_entry": { "$ref": "#/components/examples/DNSPutRequestExample" } } } } }, "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "404": { "description": "Not found" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/dns/{domainName}/export": { "parameters": [ { "in": "path", "name": "domainName", "required": true, "schema": { "$ref": "#/components/schemas/DomainName" }, "description": "Domain Name" } ], "get": { "summary": "Export DNS Zone", "description": "Export DNS zone records in standard RFC 1035 zone file format", "operationId": "dnsExportZone", "responses": { "200": { "description": "Success", "content": { "text/plain": { "schema": { "type": "string", "description": "Standard BIND zone file contents" }, "examples": { "default": { "summary": "Standard zone export", "value": "$ORIGIN example.com.\n$TTL 300\n@ IN SOA ns1.onlydns.com. hostmaster.onlydns.com. 2026102701 10800 3600 604800 300\n@ IN NS ns1.onlydns.com.\n@ IN NS ns2.onlydns.us.\n@ IN A 192.0.2.1\nwww IN CNAME example.com.\n" } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "404": { "description": "Not found" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/dns/{domainName}/scan": { "parameters": [ { "in": "path", "name": "domainName", "required": true, "schema": { "$ref": "#/components/schemas/DomainName" }, "description": "Domain Name" } ], "get": { "summary": "Scan Domain DNS Records", "description": "Automatically discover published DNS records for the domain", "operationId": "dnsScanDomain", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DNSScanResponse" }, "examples": { "default": { "summary": "Discovered DNS records", "value": [ { "name": "example.com.", "type": "A", "ttl": 300, "records": [ "192.0.2.1" ] }, { "name": "www.example.com.", "type": "CNAME", "ttl": 300, "records": [ "example.com." ] }, { "name": "example.com.", "type": "MX", "ttl": 300, "records": [ "10 mail.example.com." ] } ] } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/dns/tsig": { "get": { "summary": "Get TSIG Keys", "description": "Get all DNS TSIG keys for the account", "operationId": "dnsTsigKeys", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DNSTsigKeysResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "Create TSIG Key", "description": "Create a new TSIG key for the account. A TSIG key may be used on multiple domains.", "operationId": "createTsigKey", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DNSTsigKeyCreateRequest" }, "examples": { "general_entry": { "$ref": "#/components/examples/DNSTsigKeyCreateRequestExample" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DNSTsigKeyCreateResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/dns/{domainName}/dnssec": { "parameters": [ { "in": "path", "name": "domainName", "required": true, "schema": { "$ref": "#/components/schemas/DomainName" }, "description": "Domain Name" } ], "get": { "summary": "Get DNSSEC status", "description": "Get DNSSEC status for the domain", "operationId": "dnsDnssecStatus", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DNSDnssecStatusResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "summary": "Enable DNSSEC", "description": "Enable DNSSEC for the domain", "operationId": "dnsDnssecEnable", "responses": { "201": { "description": "Success" }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "summary": "Disable DNSSEC", "description": "Disable DNSSEC for the domain", "operationId": "dnsDnssecDisable", "responses": { "204": { "description": "Success" }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/dns/tsig/{key}": { "parameters": [ { "in": "path", "name": "key", "required": true, "schema": { "$ref": "#/components/schemas/TsigKey" }, "description": "TSIG Key Name" } ], "get": { "summary": "Get TSIG Key", "description": "Get details for TSIG key", "operationId": "dnsTsigKey", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DNSTsigKeyResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/dns/{domainName}/tsig": { "parameters": [ { "in": "path", "name": "domainName", "required": true, "schema": { "$ref": "#/components/schemas/DomainName" }, "description": "Domain Name" } ], "get": { "summary": "Get Domain TSIG Permissions", "description": "Get all TSIG keys and permissions configured on a domain", "operationId": "getDomainTsig", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainTsigKeysResponse" }, "examples": { "default": { "summary": "Configured Domain TSIG Keys", "value": { "example-key-1": { "allowAxfr": true, "allowDnsUpdate": false }, "example-key-2": { "allowAxfr": false, "allowDnsUpdate": true, "subdomains": [ "_acme_challenge" ] } } } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "summary": "Domain Delete TSIG", "description": "Delete all TSIG keys from a domain", "operationId": "deleteDomainTsig", "responses": { "201": { "description": "Success" }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/dns/{domainName}/tsig/{key}": { "parameters": [ { "in": "path", "name": "domainName", "required": true, "schema": { "$ref": "#/components/schemas/DomainName" }, "description": "Domain Name" }, { "in": "path", "name": "key", "required": true, "schema": { "$ref": "#/components/schemas/TsigKey" }, "description": "TSIG Key Name" } ], "patch": { "summary": "Domain Update TSIG Key", "description": "Update the TSIG key access settings on a domain", "operationId": "patchDomainTsig", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/patchDomainTsigRequest" }, "examples": { "full_access": { "summary": "Full Zone DNS Update & AXFR Access", "value": { "allowAxfr": true, "allowDnsUpdate": true } }, "subdomain_restricted": { "summary": "Subdomain-Restricted DNS Update Access", "value": { "allowAxfr": false, "allowDnsUpdate": true, "subdomains": [ "_acme_challenge" ] } } } } } }, "responses": { "201": { "description": "Success" }, "400": { "description": "Bad request" }, "401": { "description": "Access token is missing or invalid" }, "503": { "description": "Backend system reported error condition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "ErrorResponse": { "description": "Error Response", "type": "object", "properties": { "lang": { "type": "string", "enum": [ "en-US" ] }, "errorCode": { "type": "integer" }, "title": { "type": "string", "description": "Error title" }, "description": { "description": "A description of the error that occurred", "type": "array", "items": { "type": "string" } } } }, "DNSDnssecStatusResponse": { "description": "DNSSEC Status Response", "type": "object", "properties": { "enabled": { "type": "boolean" }, "nsec3param": { "type": "string" }, "keys": { "description": "DNSSEC DS keys", "type": "array", "items": { "$ref": "#/components/schemas/DNSSECDsKey" } } } }, "DNSTsigKeyResponse": { "description": "DNS TSIG Key Response", "type": "object", "properties": { "name": { "type": "string" }, "algorithm": { "$ref": "#/components/schemas/TsigAlgorithm" }, "key": { "type": "string" } } }, "DNSTsigKeysResponse": { "description": "DNS TSIG Keys Response", "type": "object", "properties": { "tsigKeys": { "type": "array", "items": { "$ref": "#/components/schemas/DNSTsigKeyResponse" } } } }, "DNSSECDsKey": { "description": "DNSSEC DS key", "type": "object", "properties": { "keyTag": { "type": "integer" }, "algorithm": { "$ref": "#/components/schemas/DNSSECKeyAlgorithm" }, "digestType": { "$ref": "#/components/schemas/DNSSECKeyDigestType" }, "digest": { "type": "string" } } }, "DNSSECKeyDigestType": { "description": "DNSSEC Key Digest Type", "type": "integer", "enum": [ 1, 2, 3, 4 ], "x-enumDescriptions": { "1": "SHA-1", "2": "SHA-256", "3": "GOST R 34.11-94", "4": "SHA-384" } }, "DNSSECKeyAlgorithm": { "description": "DNSSEC Key Algorithm", "type": "integer", "enum": [ 1, 2, 3, 5, 6, 7, 8, 10, 12, 13, 14, 15, 16, 17, 23 ], "x-enumDescriptions": { "1": "RSA/MD5 (deprecated)", "2": "Diffie-Hellman DH", "3": "DSA/SHA1 (deprecated)", "5": "RSA/SHA-1", "6": "DSA-NSEC3-SHA1", "7": "RSASHA1-NSEC3-SHA1", "8": "RSA/SHA-256", "10": "RSA/SHA-512", "12": "GOST R 34.10-2001", "13": "ECDSA Curve P-256 with SHA-256", "14": "ECDSA Curve P-384 with SHA-384", "15": "ED25519", "16": "ED448", "17": "SM2SM3", "23": "ECC-GOST12" } }, "TsigKey": { "description": "DNS TSIG Key", "type": "string" }, "TsigAlgorithm": { "description": "TSIG key algorithm", "type": "string", "enum": [ "mac-md5", "hmac-sha1", "hmac-sha224", "hmac-sha256", "hmac-sha384", "hmac-sha512" ] }, "DNSDomainCreateRequest": { "description": "DNS Domain Create Request", "type": "object", "properties": { "domain": { "$ref": "#/components/schemas/DomainName" } }, "required": [ "domain" ] }, "DNSTsigKeyCreateRequest": { "description": "DNS TSIG Key Create Request", "type": "object", "properties": { "algorithm": { "$ref": "#/components/schemas/TsigAlgorithm" } } }, "DNSTsigKeyCreateResponse": { "description": "DNS TSIG Key Create Response", "$ref": "#/components/schemas/DNSTsigKeyResponse" }, "patchDomainTsigRequest": { "description": "Modify TSIG on Domain Request", "type": "object", "properties": { "allowAxfr": { "type": "boolean", "description": "Whether to allow AXFR transfers for this domain+TSIG key" }, "allowDnsUpdate": { "type": "boolean", "description": "Whether to allow DNS updates for this domain+TSIG key" }, "subdomains": { "type": "array", "items": { "type": "string" }, "description": "Optional list of allowed subdomains (e.g. [\"_acme_challenge\"]). If specified, DNS updates are restricted to these subdomains." } }, "required": [ "allowAxfr", "allowDnsUpdate" ] }, "DomainTsigPermissions": { "description": "Domain TSIG Permissions", "type": "object", "properties": { "allowAxfr": { "type": "boolean", "description": "Whether AXFR transfers are allowed for this TSIG key" }, "allowDnsUpdate": { "type": "boolean", "description": "Whether DNS updates are allowed for this TSIG key" }, "subdomains": { "type": "array", "items": { "type": "string" }, "description": "Subdomains restricted for DNS update" } }, "required": [ "allowAxfr", "allowDnsUpdate" ] }, "DomainTsigKeysResponse": { "description": "Domain TSIG Keys and Permissions Response", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DomainTsigPermissions" } }, "DomainName": { "description": "Domain Name", "type": "string", "example": "example.com" }, "NameServer": { "description": "Name Server", "type": "string", "example": "ns1.example.com" }, "dnssec": { "type": "object", "properties": { "keyTag": { "type": "integer" }, "algorithm": { "type": "integer", "enum": [ 3, 5, 7, 8, 10, 12, 13, 14, 15, 16, 17, 23 ], "x-enumDescriptions": { "3": "DSA/SHA-1", "5": "RSA/SHA-1", "7": "RSASHA1-NSEC3-SHA1", "8": "RSA/SHA-256", "10": "RSA/SHA-512", "12": "GOST R 34.10-2001", "13": "ECDSA/SHA-256", "14": "ECDSA/SHA-384", "15": "ED25519", "16": "ED448", "17": "SM2SM3", "23": "ECC-GOST12" } }, "digestType": { "type": "integer", "enum": [ 1, 2 ], "x-enumDescriptions": { "1": "SHA-1", "2": "SHA-256" } }, "digest": { "type": "string" } } }, "Date": { "type": "string", "format": "date", "example": "2023-10-29" }, "Years": { "description": "Whole number of years to register/renew", "type": "integer", "default": 1, "minimum": 1, "maximum": 10, "example": 2 }, "GetDomainListResponse": { "description": "Domain List", "type": "array", "items": { "description": "domain name", "type": "string" } }, "DNSRecord": { "description": "DNS record", "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "A", "AAAA", "MX", "CNAME", "TXT", "SRV", "CAA", "CERT", "HTTPS", "LOC", "NAPTR", "NS", "SMIMEA", "SSHFP", "SVCB", "TLSA", "URL", "PROXY" ], "x-enumDescriptions": { "A": "A", "AAAA": "AAAA", "MX": "MX", "CNAME": "CNAME", "TXT": "TXT", "SRV": "SRV", "CAA": "CAA", "CERT": "CERT", "HTTPS": "HTTPS", "LOC": "LOC", "NAPTR": "NAPTR", "NS": "NS", "SMIMEA": "SMIMEA", "SSHFP": "SSHFP", "SVCB": "SVCB", "TLSA": "TLSA", "URL": "URL Forwarding (Non-Standard Record)", "PROXY": "Proxy record will load the remote content masked. (Non-Standard Record, Additional Fees May Apply)" } }, "ttl": { "type": "integer" }, "records": { "description": "One or more records for this hostname + type combination.", "type": "array", "items": { "description": "Record value", "type": "string" } } } }, "DNSGetRecordsResponse": { "description": "Response to a get for dns records", "type": "array", "items": { "$ref": "#/components/schemas/DNSRecord" } }, "DNSScanResponse": { "description": "Response containing discovered DNS records for a domain", "type": "array", "items": { "$ref": "#/components/schemas/DNSRecord" } }, "DNSPutRequest": { "description": "Request payload used for updating DNS records", "type": "array", "items": { "$ref": "#/components/schemas/DNSRecord" } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "examples": { "DNSDomainCreateRequestExample": { "summary": "Create a DNS Domain", "value": { "domain": "example.com" } }, "DNSPutRequestExample": { "summary": "Replace DNS Records Example", "value": [ { "name": "example.com.", "type": "A", "ttl": 300, "records": [ "192.0.2.1" ] }, { "name": "www.example.com.", "type": "CNAME", "ttl": 300, "records": [ "example.com." ] } ] }, "DNSTsigKeyCreateRequestExample": { "summary": "Create TSIG Key Request", "value": { "algorithm": "hmac-sha256" } } }, "parameters": { "PaginationOffset": { "name": "offset", "in": "query", "description": "The offset number to retrieve.", "schema": { "type": "integer", "default": 0, "example": 50 } }, "PaginationLimit": { "name": "limit", "in": "query", "description": "The number of domain results per query.", "schema": { "type": "integer", "default": 200, "maximum": 1000, "example": 500 } } } }, "security": [ { "BearerAuth": [] } ] }