{"openapi":"3.1.0","info":{"title":"Nossic DNS API","version":"1.0.0","description":"Manage your domains and DNS records on Nossic DNS. Authenticate with an API key from the Nossic DNS app (API keys page): `Authorization: Bearer ndns_…`. Human-readable docs: https://app.dns.nossic.uk/docs"},"servers":[{"url":"https://app.dns.nossic.uk/api/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"Account"},{"name":"Domains"},{"name":"Records"},{"name":"Record sets"}],"paths":{"/me":{"get":{"tags":["Account"],"summary":"The key in use, and the name servers to set at your registrar","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains":{"get":{"tags":["Domains"],"summary":"List the domains this key can use","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Domains"],"summary":"Add a domain","description":"Needs a key for all your domains, with write access. Then set the domain's name servers at your registrar to the ones in `nameservers`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"example.com"}}}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"$ref":"#/components/schemas/Domain"}}}}}},"400":{"description":"Not a domain you can add, or over the limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Already in another account (or yours): see error.claim to prove it's yours","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimNeeded"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{domain}":{"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"example.com"}],"get":{"tags":["Domains"],"summary":"A domain, with its status and serial","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"allOf":[{"$ref":"#/components/schemas/Domain"},{"type":"object","properties":{"serial":{"type":"integer"},"records":{"type":"integer"}}}]}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Domains"],"summary":"Remove a domain and all its records","description":"Change the name servers at your registrar first. The domain stays reserved for you for 30 days.","responses":{"204":{"description":"Removed"},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key can't remove domains","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not in your account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{domain}/check":{"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"example.com"}],"post":{"tags":["Domains"],"summary":"Check now whether the registry points the domain at Nossic DNS","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"$ref":"#/components/schemas/Domain"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{domain}/claim":{"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"example.com"}],"post":{"tags":["Domains"],"summary":"Verify a claim on a domain held by another account","description":"After adding the TXT record from the 409 response at the domain's current DNS provider.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"$ref":"#/components/schemas/Domain"}}}}}},"400":{"description":"TXT record not found yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{domain}/zone":{"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"example.com"}],"get":{"tags":["Domains"],"summary":"Export the zone as a zone file","responses":{"200":{"description":"Zone file","content":{"text/dns":{"schema":{"type":"string"}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{domain}/records":{"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"example.com"}],"get":{"tags":["Records"],"summary":"List records","parameters":[{"name":"name","in":"query","schema":{"type":"string"},"description":"Only this name (@, www, …)"},{"name":"type","in":"query","schema":{"type":"string"},"description":"Only this type"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"serial":{"type":"integer"},"records":{"type":"array","items":{"$ref":"#/components/schemas/Record"}}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Records"],"summary":"Add a record","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordInput"}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"serial":{"type":"integer"},"record":{"$ref":"#/components/schemas/Record"}}}}}},"400":{"description":"Invalid record, or it breaks a DNS rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{domain}/records/{id}":{"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"example.com"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"r_3kQe0vV1u2zXl9aB"}],"get":{"tags":["Records"],"summary":"One record","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"serial":{"type":"integer"},"record":{"$ref":"#/components/schemas/Record"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Records"],"summary":"Change a record","description":"Send the parts to change; the rest stay. The record gets a new id.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"serial":{"type":"integer"},"record":{"$ref":"#/components/schemas/Record"}}}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Records"],"summary":"Delete a record","responses":{"204":{"description":"Deleted"},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domains/{domain}/rrsets/{name}/{type}":{"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"example.com"},{"name":"name","in":"path","required":true,"schema":{"type":"string"},"description":"Name within the domain: @ for the domain itself, or a name such as www or _acme-challenge.","example":"_acme-challenge"},{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS","PTR"]},"example":"TXT"}],"get":{"tags":["Record sets"],"summary":"All records of one name and type","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RRset"}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such records","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"tags":["Record sets"],"summary":"Replace all records of one name and type","description":"Creates the set if needed. Handy for ACME DNS-01 challenges and dynamic DNS.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["records"],"properties":{"ttl":{"type":"integer","default":3600},"records":{"type":"array","items":{"oneOf":[{"type":"string","description":"content"},{"type":"object","properties":{"content":{"type":"string"},"fields":{"type":"object"}}}]}}}},"example":{"ttl":60,"records":["dGhpcyBpcyBhIGNoYWxsZW5nZQ"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RRset"}}}},"400":{"description":"Invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Record sets"],"summary":"Delete all records of one name and type","responses":{"204":{"description":"Deleted"},"401":{"description":"Missing, invalid, expired or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such records","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key from the Nossic DNS app: ndns_…"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"ClaimNeeded":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"const":"domain_taken"},"message":{"type":"string"},"claim":{"type":"object","properties":{"name":{"type":"string","example":"_nossic-dns-claim.example.com"},"type":{"const":"TXT"},"value":{"type":"string"}}}}}}},"Me":{"type":"object","properties":{"key":{"type":"object","properties":{"id":{"type":"string"},"access":{"enum":["all","selected"]},"domains":{"type":"array","items":{"type":"string"}},"permission":{"enum":["read","read-write"]}}},"nameservers":{"type":"array","items":{"type":"string"},"example":["ns1.nossic.uk","ns2.nossic.uk"]}}},"Domain":{"type":"object","properties":{"name":{"type":"string","example":"example.com"},"kind":{"enum":["tenant","system"]},"status":{"enum":["pending","active","partial","moved"],"description":"pending: not pointed at Nossic DNS yet; active: the registry uses our name servers; partial: only some of them; moved: was active, now points elsewhere"},"nameservers":{"type":"array","items":{"type":"string"},"example":["ns1.nossic.uk","ns2.nossic.uk"],"description":"Set these at your registrar"},"delegatedTo":{"type":"array","items":{"type":"string"},"description":"Name servers the registry gave out at the last check"},"createdAt":{"type":"string","format":"date-time"},"checkedAt":{"type":["string","null"],"format":"date-time"},"activeAt":{"type":["string","null"],"format":"date-time"}}},"Record":{"type":"object","properties":{"id":{"type":"string","description":"Stays the same while the record is unchanged"},"name":{"type":"string","example":"www","description":"@ for the domain itself"},"fqdn":{"type":"string","example":"www.example.com."},"type":{"type":"string","example":"A"},"ttl":{"type":"integer","example":3600},"content":{"type":"string","example":"192.0.2.10","description":"The value as one string (TXT unquoted)"},"data":{"type":"string","description":"The value in zone-file form"},"fields":{"type":"object","additionalProperties":{"type":"string"}},"locked":{"type":["string","null"],"description":"Why it can't be changed (the SOA and the domain's own NS records)"}}},"RecordInput":{"type":"object","required":["type"],"properties":{"name":{"type":"string","default":"@","example":"www"},"type":{"enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS","PTR"]},"ttl":{"type":"integer","minimum":30,"maximum":604800,"default":3600},"content":{"type":"string","description":"A: 192.0.2.10 · AAAA: 2001:db8::1 · CNAME/NS/PTR: host.example.com · MX: 10 mail.example.com · TXT: any text · SRV: 0 5 443 host.example.com · CAA: 0 issue letsencrypt.org"},"fields":{"type":"object","description":"Instead of content: address · target · priority+target · text · priority+weight+port+target · flags+tag+value"}},"example":{"name":"www","type":"A","ttl":300,"content":"192.0.2.10"}},"RRset":{"type":"object","properties":{"serial":{"type":"integer"},"ttl":{"type":"integer"},"records":{"type":"array","items":{"$ref":"#/components/schemas/Record"}}}}}}}