Docs

Plonki lets software and AI agents search, register and configure domain names. Use the MCP server from an AI tool, or the REST API from your own code. Both do the same things.

Quick start

Sign in and create an API key. Start with a plk_test_ key: it uses a simulated registry and costs nothing.
Search: GET /v1/domains/search?q=acme
Register: POST /v1/domains with the domain, max_price and an Idempotency-Key.
Connect it: POST /v1/domains/acme.com/point with {"target":"acme.vercel.app"}

MCP server

URL: https://plonki.com.au/mcp (Streamable HTTP). Clients that support OAuth will open a sign-in page the first time. Clients that don't can send an API key as a Bearer token.

Claude Code

claude mcp add --transport http plonki https://plonki.com.au/mcp

Claude and ChatGPT

Add a custom connector (in ChatGPT, under Apps with developer mode on) with the URL https://plonki.com.au/mcp, then sign in.

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "plonki": {
      "url": "https://plonki.com.au/mcp"
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "plonki": {
      "type": "http",
      "url": "https://plonki.com.au/mcp"
    }
  }
}

Any client, with an API key

{
  "mcpServers": {
    "plonki": {
      "url": "https://plonki.com.au/mcp",
      "headers": {
        "Authorization": "Bearer plk_live_..."
      }
    }
  }
}

Tools

`search_domains`	Availability and price for a domain or phrase
`suggest_domains`	Available ideas from keywords
`register_domain`	Buy a domain (asks the user first)
`get_order`	Order status, for checkout and slow registrations
`point_domain`	DNS for Vercel, Netlify, Cloudflare Pages, Render, GitHub Pages or an IP
`set_nameservers`	Hand DNS to another provider
`list_dns_records`, `add_dns_record`, `delete_dns_record`	Manage records
`list_domains`, `get_domain`, `renew_domain`, `get_transfer_code`	Manage domains
`list_contacts`, `create_contact`	Domain owner details
`get_account`, `create_topup_link`, `get_prices`	Balance and prices

REST API authentication

Base URL https://plonki.com.au/v1. Send your key in the Authorization header. Full spec: /openapi.json.

curl https://plonki.com.au/v1/account -H "Authorization: Bearer plk_test_..."

Search

curl "https://plonki.com.au/v1/domains/search?q=acme%20coffee&tlds=com,com.au,io" \
  -H "Authorization: Bearer $PLONKI_KEY"

{
  "results": [
    { "domain": "acmecoffee.com", "available": false, "price": null },
    { "domain": "acmecoffee.com.au", "available": true, "premium": false,
      "currency": "AUD", "price": { "register": 2499, "renew": 2499, "min_years": 1 } }
  ]
}

Prices are integer cents per year.

Register

curl https://plonki.com.au/v1/domains \
  -H "Authorization: Bearer $PLONKI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "acmecoffee.com.au",
    "years": 1,
    "max_price": 2499,
    "external_ref": "your-customer-123",
    "contact": {
      "first_name": "Sam", "last_name": "Lee", "email": "sam@acme.com.au",
      "phone": "+61.412345678", "address1": "1 Smith St", "city": "Melbourne",
      "state": "VIC", "postcode": "3000", "country": "AU"
    },
    "au_eligibility": {
      "registrant_name": "Acme Coffee Pty Ltd", "registrant_id": "12345678901",
      "registrant_id_type": "ABN", "eligibility_type": "Company"
    }
  }'

The response is an order:

completed (201): paid from balance and registered.
awaiting_payment (202): balance was short, send your user to checkout_url.
processing (202): the registry is slow, poll GET /v1/orders/:id.

The first contact you send is saved as the account default, so later registrations can leave it out. .com.au, .net.au, .org.au and .au names need au_eligibility.

Connect and DNS

curl https://plonki.com.au/v1/domains/acmecoffee.com.au/point \
  -H "Authorization: Bearer $PLONKI_KEY" -H "Content-Type: application/json" \
  -d '{"target":"acmecoffee.vercel.app"}'

Or add records directly with POST /v1/domains/:domain/dns, e.g. {"name":"@","type":"TXT","content":"google-site-verification=..."}. To use Cloudflare or another DNS host, PUT /v1/domains/:domain/nameservers.

Errors

{
  "error": {
    "code": "contact_required",
    "message": "A registrant contact is needed to register a domain",
    "hint": "Ask the user for the domain owner's details ... and pass them as `contact`."
  }
}

code is stable. hint is written for AI agents: it says what to do or ask next. Common codes: domain_unavailable, price_changed, contact_required, au_eligibility_required, insufficient_balance, validation_error.

Webhooks

Set a URL under Dashboard, Settings. Plonki sends order.completed and order.failed, retrying with backoff for about two hours. Verify each request:

// Plonki-Signature: t=1731000000,v1=5f2b...
const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
const expected = hmacSha256Hex(WEBHOOK_SECRET, `${t}.${rawBody}`);
if (expected !== v1 || Date.now() / 1000 - Number(t) > 300) reject();

Billing

Top up a prepaid AUD balance from the dashboard or POST /v1/billing/topup. Orders are paid from the balance instantly. If an order fails, the amount goes back to your balance.