{"openapi":"3.1.0","info":{"title":"Plonki API","version":"1.0.0","summary":"Domain registration API for software and AI agents","description":"Search, register, renew and configure domain names. Prices are integer AUD cents. Use plk_test_ keys to build against a simulated registry at no cost. Every error returns { error: { code, message, hint } }; `hint` says what to do next.","contact":{"url":"https://plonki.com.au/docs"}},"servers":[{"url":"https://plonki.com.au/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"plk_live_… or plk_test_… from the dashboard"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"}},"required":["code","message"]}}}}}}}},"paths":{"/account":{"get":{"operationId":"getAccount","summary":"Account, mode and balance","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Error"}}}},"/prices":{"get":{"operationId":"getPrices","summary":"Price per extension","parameters":[{"name":"tld","in":"query","schema":{"type":"string"},"example":"com.au"}],"responses":{"200":{"description":"Prices in AUD cents per year","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/domains/search":{"get":{"operationId":"searchDomains","summary":"Check availability and price","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"A domain (acme.com) or phrase (Acme Coffee)","example":"acme coffee"},{"name":"tlds","in":"query","schema":{"type":"string"},"description":"Comma-separated extensions","example":"com,io,com.au"},{"name":"domains","in":"query","schema":{"type":"string"},"description":"Comma-separated exact domains"}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"searchDomainsBulk","summary":"Check availability (JSON body)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"description":"A domain (acme.com) or a name/phrase (Acme Coffee). Phrases are checked across popular extensions.","type":"string","minLength":1,"maxLength":200},"domains":{"description":"Exact domains to check, up to 50","maxItems":50,"type":"array","items":{"type":"string"}},"tlds":{"description":"Extensions to try for a phrase, e.g. ['com','io','com.au']","maxItems":20,"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/domains/suggest":{"get":{"operationId":"suggestDomains","summary":"Available domain ideas from keywords","parameters":[{"name":"keywords","in":"query","required":true,"schema":{"type":"string"},"example":"dog grooming melbourne"},{"name":"tlds","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":30}}],"responses":{"200":{"description":"Suggestions","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/domains":{"get":{"operationId":"listDomains","summary":"Domains in the account","parameters":[{"name":"external_ref","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Domains","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"registerDomain","summary":"Register a domain","description":"Pays from balance (201, completed) or returns an order with checkout_url for the user to pay (202, awaiting_payment). Poll GET /orders/{id} or listen for the order.completed webhook.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Retrying with the same key returns the original order instead of buying twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"The domain to register, e.g. acme.com"},"years":{"default":1,"type":"integer","minimum":1,"maximum":10},"max_price":{"description":"Most you will pay, in AUD cents, for the whole order. Use total from search/quote. Order fails if the price is higher.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"contact_id":{"description":"Saved registrant contact. Defaults to the account's default contact.","type":"string"},"contact":{"description":"Registrant details, if there's no saved contact. Saved for next time.","type":"object","properties":{"first_name":{"type":"string","minLength":1,"maxLength":60},"last_name":{"type":"string","minLength":1,"maxLength":60},"organisation":{"type":"string","maxLength":120},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"description":"Mobile, e.g. 0412 345 678, +61 412 345 678 or +61.412345678","type":"string","pattern":"^\\+\\d{1,3}\\.\\d{4,14}$"},"address1":{"type":"string","minLength":1,"maxLength":120},"address2":{"type":"string","maxLength":120},"city":{"type":"string","minLength":1,"maxLength":60},"state":{"type":"string","minLength":1,"maxLength":60,"description":"For Australia use the abbreviation: NSW, VIC, QLD, SA, WA, TAS, ACT, NT"},"postcode":{"type":"string","minLength":2,"maxLength":12},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2, e.g. AU, US, GB"}},"required":["first_name","last_name","email","phone","address1","city","state","postcode","country"]},"au_eligibility":{"type":"object","properties":{"registrant_name":{"type":"string","minLength":1,"maxLength":255,"description":"Legal name of the registrant (company or person)"},"registrant_id":{"type":"string","minLength":1,"maxLength":50,"description":"ABN, ACN or other ID number, digits only"},"registrant_id_type":{"type":"string","enum":["ABN","ACN","OTHER"],"description":"OTHER covers state business registration numbers and incorporated associations"},"eligibility_type":{"type":"string","enum":["Company","Sole Trader","Partnership","Registered Business","Trademark Owner","Pending TM Owner","Incorporated Association","Non-profit Organisation","Charity","Club","Industry Body","Trade Union","Commercial Statutory Body","Political Party","Religious/Church Group","Citizen/Resident","Child Care Centre","Government School","Non-Government School","Pre-school","Higher Education Institution","Training Organisation","Research Organisation","National Body","Other"],"description":"Entity type. Most businesses are 'Company' (Pty Ltd), 'Sole Trader' or 'Registered Business'. .id.au only allows 'Citizen/Resident'."},"eligibility_name":{"description":"Trading or business name the domain is based on, if different from registrant_name","type":"string","maxLength":255},"eligibility_id":{"description":"ID that backs eligibility_name (e.g. a trademark number or state business number)","type":"string","maxLength":50},"eligibility_id_type":{"type":"string","enum":["ABN","ACN","TM","OTHER","ACT BN","NSW BN","NT BN","QLD BN","SA BN","TAS BN","VIC BN","WA BN"]}},"required":["registrant_name","registrant_id","registrant_id_type","eligibility_type"],"description":"Required for .com.au, .net.au, .org.au, .id.au and .au names (auDA rules)"},"nameservers":{"description":"Custom nameservers. Leave empty to use Plonki DNS (needed for the DNS tools).","minItems":2,"maxItems":6,"type":"array","items":{"type":"string"}},"payment":{"default":"auto","description":"auto: use balance, or return a pay link if it's short. checkout: always return a pay link.","type":"string","enum":["auto","balance","checkout"]},"idempotency_key":{"description":"Same key returns the same order instead of buying twice","type":"string","maxLength":100},"external_ref":{"description":"Your own reference, e.g. your customer's ID","type":"string","maxLength":200}},"required":["domain"]}}}},"responses":{"201":{"description":"Order completed","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Order accepted","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/domains/{domain}":{"get":{"operationId":"getDomain","summary":"Domain details","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"acme.com"}],"responses":{"200":{"description":"Domain","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/domains/{domain}/renew":{"post":{"operationId":"renewDomain","summary":"Renew","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"acme.com"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Retrying with the same key returns the original order instead of buying twice."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"years":{"default":1,"type":"integer","minimum":1,"maximum":10},"max_price":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"payment":{"default":"auto","type":"string","enum":["auto","balance","checkout"]},"idempotency_key":{"type":"string","maxLength":100}},"required":[]}}}},"responses":{"201":{"description":"Order","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Order","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/domains/{domain}/nameservers":{"put":{"operationId":"setNameservers","summary":"Set nameservers","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"acme.com"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nameservers":{"maxItems":6,"type":"array","items":{"type":"string"},"description":"Hostnames, e.g. ['ns1.vercel-dns.com','ns2.vercel-dns.com']. Send an empty array to switch back to Plonki DNS."}},"required":["nameservers"]}}}},"responses":{"200":{"description":"Nameservers","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/domains/{domain}/point":{"post":{"operationId":"pointDomain","summary":"Point at a host (Vercel, Netlify, Cloudflare Pages, IP...)","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"acme.com"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string","description":"Where the site is hosted: an IPv4 address (76.76.21.21) or a hostname (myapp.vercel.app, myapp.pages.dev, myapp.netlify.app)"},"include_www":{"default":true,"type":"boolean"}},"required":["target"]}}}},"responses":{"200":{"description":"Records created and next steps","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/domains/{domain}/dns":{"get":{"operationId":"listDnsRecords","summary":"DNS records","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"acme.com"}],"responses":{"200":{"description":"Records","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"addDnsRecord","summary":"Add a DNS record","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"acme.com"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"default":"@","description":"Host label: '@' for the root, 'www', 'api', etc.","type":"string"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS"]},"content":{"type":"string","minLength":1,"maxLength":2048},"ttl":{"default":3600,"type":"integer","minimum":300,"maximum":86400},"priority":{"description":"MX and SRV only","type":"integer","minimum":0,"maximum":65535}},"required":["type","content"]}}}},"responses":{"201":{"description":"Record","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/domains/{domain}/dns/{id}":{"delete":{"operationId":"deleteDnsRecord","summary":"Delete a DNS record","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"acme.com"},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/domains/{domain}/transfer-code":{"get":{"operationId":"getTransferCode","summary":"EPP / auth code","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"},"example":"acme.com"}],"responses":{"200":{"description":"Code","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/orders":{"get":{"operationId":"listOrders","summary":"Recent orders","responses":{"200":{"description":"Orders","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/orders/{id}":{"get":{"operationId":"getOrder","summary":"Order status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/contacts":{"get":{"operationId":"listContacts","summary":"Registrant contacts","responses":{"200":{"description":"Contacts","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"createContact","summary":"Save a registrant contact","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string","minLength":1,"maxLength":60},"last_name":{"type":"string","minLength":1,"maxLength":60},"organisation":{"type":"string","maxLength":120},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"phone":{"description":"Mobile, e.g. 0412 345 678, +61 412 345 678 or +61.412345678","type":"string","pattern":"^\\+\\d{1,3}\\.\\d{4,14}$"},"address1":{"type":"string","minLength":1,"maxLength":120},"address2":{"type":"string","maxLength":120},"city":{"type":"string","minLength":1,"maxLength":60},"state":{"type":"string","minLength":1,"maxLength":60,"description":"For Australia use the abbreviation: NSW, VIC, QLD, SA, WA, TAS, ACT, NT"},"postcode":{"type":"string","minLength":2,"maxLength":12},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2, e.g. AU, US, GB"}},"required":["first_name","last_name","email","phone","address1","city","state","postcode","country"]}}}},"responses":{"201":{"description":"Contact","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/billing/topup":{"post":{"operationId":"createTopup","summary":"Checkout link to add balance","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","minimum":1000,"maximum":1000000,"description":"AUD cents, $10 to $10,000"}},"required":["amount"]}}}},"responses":{"200":{"description":"checkout_url","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"x-webhooks-note":"Set a webhook URL in the dashboard to receive order.completed and order.failed. Verify Plonki-Signature: t=<ts>,v1=HMAC_SHA256(secret, `${t}.${body}`)."}