Porkbun (official)

Create many DNS records on a Porkbun domain in one call — the companion to scan_dns_records for keeping a transferred domain working. Pass `records` to import an exact list (preferred when you read the zone from the old registrar's API), or omit it entirely to import whatever a live scan of the domain discovers. Idempotent: a record that already exists is reported in `skipped`, not `failed`, so this is safe to re-run and safe as a converge step. Individual failures are listed in `failures` while everything else still imports. NS and SOA entries are ignored on purpose — they describe the delegation, not the zone. Important: imported records have no effect until the domain actually points at Porkbun's nameservers, so check get_nameservers afterwards and use update_nameservers when the user is ready to cut over — when the domain is delegated elsewhere the response also says so in `warnings`. Maximum 500 records per call.

List every domain in the account with its Cloudflare eligibility: `state` is eligible / warn / blocked / connected / inprogress, each with a human-readable reason (DNSSEC live, custom nameservers, uses Porkbun hosting, etc). Read this BEFORE queueing so you can tell the user what will move and what won't. Works even when the Cloudflare account isn't connected yet, so you can plan while the user authorizes.

List all DNS records for a domain in the authenticated account. Returns each record's id, type (A, AAAA, CNAME, MX, TXT, etc.), name (subdomain or empty for apex), content, ttl, and priority (where applicable). The `id` field is required when editing or deleting a specific record.

List the saved versions of a domain's DNS zone, newest first. **DNS is the one layer with no undo built in, and this is it** — if a record was deleted or edited by mistake you do not need to know what it used to say, you can look. Restore points are captured automatically before the first write to a zone in each hour (so a run of edits costs one point, not one per record), before any bulk import or zone wipe, and before any restore. Read two fields carefully. `recordCount` is the size of the zone AS IT WAS at that moment, not now — a drop between consecutive points is where records were lost. `matchesLive` marks the point the zone currently sits on, which is where you are, not where you want to go. Up to 50 are returned. Restore points only cover the zone as Porkbun held it; a domain on someone else's nameservers has nothing here.

List the DNSSEC DS records currently submitted to the registry for a domain. Returns key tag, algorithm, digest type, and digest. Use this to verify DNSSEC chain-of-trust setup. Empty array = DNSSEC not configured.

List the available Porkbun API documentation topics. Returns the docs index (Markdown) — every per-topic page (e.g. dns, domain, webhooks, ssl, pricing) with a one-line description and endpoint count, plus links to the full reference and the OpenAPI spec. Use this first to discover what docs exist, then read_doc to read one. Grounds an agent in Porkbun's own docs without leaving the conversation.

List domains in the authenticated Porkbun account. Returns one page (up to 1000) with metadata: expire date, auto-renew, security lock, WHOIS privacy, API access opt-in, and notLocal flag. Filters (all optional): - `domain`: exact match. Returns 0 or 1. - `name_contains`: substring search on domain name. - `tlds`: limit to these TLDs (no leading dot). - `expiring_within_days`: only domains expiring within N days. Useful for renewal automation. - `auto_renew`: 'yes' or 'no'. - `api_access`: 'yes' or 'no'. Filter to domains an API key can actually operate on — eliminates `API_ACCESS_DISABLED` errors downstream. - `sort_name`: 'domain' | 'tld' | 'create_date' | 'expire_date'. Default expire_date. - `sort_direction`: 'asc' | 'desc'. Default asc. For a single domain by name, use `get_domain` instead — cleaner shape and 404-on-not-found semantics.

List glue records for a domain. Glue records associate a host (e.g. `ns1.example.com`) with one or more IP addresses at the registry, used when running your own nameservers on the same domain they serve. Returns the host, IPv4 addresses, and IPv6 addresses for each glue record.

List file/directory names under an optional `path` in a domain's Secure Static Hosting space. Calls the Porkbun Hosting API (https://porkbun.com/llms/hosting).

List the hosting plans provisionable via the API, with price (cents — pass as `acknowledged_cost_cents` to create_hosting), interval, trial length, and features. Use this to discover plans + costs before create_hosting rather than hardcoding them. Currently Secure Static Hosting; more products are added over time.

Browse domains for sale on the Porkbun marketplace (aftermarket — domains owned by other users, not new registrations). Returns each listing's domain, TLD, SLD length, price (in USD), and listing date. Filters (all optional, server-side, mirroring the porkbun.com/marketplace UI): - `query`: SLD substring match. Multi-word queries: prefix a word with `-` to exclude it (e.g. `"ai -test"` matches SLDs containing 'ai' but not 'test'). - `tlds`: limit to a list of TLDs (without the leading dot). - `sld_length_min`, `sld_length_max`: SLD character length bounds. - `sort_name`: `domain` | `tld` | `price` | `sld_length`. - `sort_direction`: `asc` | `desc`. When any filter is set, server returns up to 1000 matching listings. With no filters, supports raw pagination via `start` / `limit` (max 5000).

List all in-progress and recent inbound domain transfers for the authenticated account. Returns each transfer's domain, status (`NEW`, `PENDINGAUTH`, `PENDINGSUBMIT`, `PENDINGTRANSFER`, `DONE`, `CANCELED`, etc.), and create date. Use this to monitor transfers initiated by `transfer_domain`.

List all URL forwarding rules configured for a domain. Each entry includes its `id` (used by `delete_url_forward`), the source subdomain, the destination URL, the redirect `type` (permanent/temporary/masked), the exact `redirectType` code (301/302/307/masked — distinguishes 302 from 307), and whether the request path and wildcards are forwarded.

List recent webhook delivery attempts (newest first), across all endpoints or filtered to one. Each row reports event type, event id, status (PENDING|PROCESSING|DELIVERED|FAILED), attempt count, HTTP status, and last error. Delivery history is retained ~30 days. Use this to audit what was sent and to find a delivery id to resend. The payload is omitted here — use get_webhook_delivery for the full signed payload.

List the webhook endpoints registered on the authenticated account. Each endpoint includes its id, URL, subscribed events, status (ACTIVE|DISABLED), consecutive failure count, last success/failure timestamps, last error, and signing secret. Porkbun POSTs a signed JSON payload to each endpoint when subscribed events occur; deliveries are signed with the endpoint's secret via HMAC-SHA256 over `{timestamp}.{rawBody}` and sent in the `X-Porkbun-Signature` header.

CLOUD FOR WORDPRESS ONLY. List the WordPress application passwords on a domain's site (uuid, name, created, last used) so you can audit them or pick one to revoke. Metadata only — the passwords themselves can never be re-read.

Create a directory (and any missing parent directories) at `path` in a domain's Secure Static Hosting space. deploy_site already auto-creates the directories in a file's path, so use this only to stand up an empty directory explicitly. Calls the Porkbun Hosting API (https://porkbun.com/llms/hosting).

Get a schema-accurate EXAMPLE response for any API endpoint with NO credentials — nothing to set up. Mirrors the real path under /mock (e.g. path `domain/listAll` or `dns/create/example.com`). Touches no datastore and returns the exact shape the live API would. Set `error: true` to see the error-response shape instead. Use it to learn/verify response shapes before wiring up real or sandbox keys. Omit `path` (or pass empty) to list every mockable endpoint.

Verify the Porkbun API connection and credentials. Returns the caller's public IP and whether the API key is valid. Use this as a first sanity check before making other calls.

Ask whether a change is about to break a domain, BEFORE making it. Read-only, free, and the right thing to call before changing nameservers, transferring a domain out, or enabling DNSSEC. Every check comes from a real incident, so these are the failures where a zone looks fine and stops working anyway. Read `blockers` first — those will break something. `warnings` will not break outright but are usually what the user notices next. `safe` is true only when both are empty. Each check names the rule it comes from and carries a `next_action`, so you can explain the finding rather than just report it. The two an agent should treat as hard stops: - `dnssec-active` — DS records are published at the registry, so new nameservers will serve answers that do not match them and validating resolvers will refuse the WHOLE zone. The domain goes dark rather than degrading. DNSSEC has to be removed and the DS TTL waited out BEFORE the nameservers change. Never move delegation past this one. - `spf-duplicate` / `spf-lookups` — RFC 7208 permerrors that make SPF fail for every sender, so the domain's mail is already being degraded whether or not the user has noticed. Check `nameservers-ours` before you read anything else: it says whether this zone is what the world resolves at all. A domain delegated to another provider still accepts every DNS write here and none of them take effect, and the mixed case (some of the delegated nameservers are Porkbun's, some are not) means resolvers disagree query to query. The one worth explaining because nobody expects it: `wildcard-shadowed`. Under RFC 4592 a wildcard answers only names that do NOT exist in the zone, so a name holding just an MX or TXT record stops inheriting the wildcard's address and stops resolving — with nothing in the zone looking wrong.

Create the Porkbun DNS zone for a domain whose inbound transfer is held, so records can be added before the domain moves. Step 2 of the no-downtime sequence (transfer_domain with hold_for_dns_setup, prepare_transfer, import_dns_records, start_transfer). Returns the Porkbun nameservers. The zone is created deliberately, not as a side effect of the first record write, which is why this call exists.

Show exactly which DNS records would be copied into Cloudflare for a domain, and which would be dropped, WITHOUT queueing anything. Use this to tell a user what a move will do to their DNS before committing. Records are always created DNS-only (grey cloud); proxying is a separate step via set_cloudflare_proxy.

Read a Porkbun documentation page as Markdown. Pass a `topic` from list_doc_topics (e.g. `dns`, `domain`, `webhooks`, `ssl`, `pricing`, `account`, `marketplace`). Special values: `overview` (the llms.txt orientation), `full` (the entire flat reference — every endpoint), or `index` (the topic list). Returns the page's full Markdown, including endpoint signatures, parameters, and curl examples.

**Spends account credit.** Registers a new domain on the authenticated Porkbun account. The `cost_cents` parameter must exactly match the current registration price returned by `check_domain` (in cents) — Porkbun rejects mismatched quotes. Workflow: call `check_domain` first to get availability + price, confirm the spend with the user, then call this. The order is idempotency-safe: retries within 24 hours via the same Idempotency-Key return the original response without re-charging. Premium domains, .uk, and a handful of registry-specific TLDs cannot be registered via API and must be done on the website. The account's email and phone number must be verified. A single API registration cannot exceed $100 (`ORDER_TOO_LARGE`); above that the user has to register on the website. **Money comes from prepaid account credit.** The purchase itself charges the credit balance, never a card. If the balance is short, the call fails with `INSUFFICIENT_FUNDS` carrying `cost`, `balance`, `shortfall` and **`topUpAvailable`** (`dry_run: true` reports the same without charging). When `topUpAvailable` is true a card is saved: tell the user the shortfall and offer to top up — with their OK, call `top_up_account_credit` (`amount_cents` at least `topUpAmountToCover`, or omit it for their configured amount) and then retry this exact call. Only when it is false does the user have to add credit at https://porkbun.com/account/credit. Suggest `configure_auto_topup` if they want this to happen automatically next time. Money parameters are integer cents: state amounts to the user in dollars (`cost_cents: 1108` is $11.08). If you do not charge cards on a user's behalf, hand it back instead: tell them the shortfall and that they can add it with **buy account credit** at https://porkbun.com/account/credit, then retry once they have.

**Spends account credit.** Renews an existing domain in the authenticated account. The `cost_cents` parameter must exactly match the current renewal price returned by `check_domain` (in cents). The domain must be opted in to API access (per-domain or global toggle in account settings). Domains registered within the last 30 days, or already renewed within the last 30 days, cannot be renewed yet — the API returns `RENEWAL_TOO_SOON`. Premium domain renewals are not supported via API. Idempotency-safe: retries within 24 hours don't double-charge. **Money comes from prepaid account credit.** The purchase itself charges the credit balance, never a card. If the balance is short, the call fails with `INSUFFICIENT_FUNDS` carrying `cost`, `balance`, `shortfall` and **`topUpAvailable`** (`dry_run: true` reports the same without charging). When `topUpAvailable` is true a card is saved: tell the user the shortfall and offer to top up — with their OK, call `top_up_account_credit` (`amount_cents` at least `topUpAmountToCover`, or omit it for their configured amount) and then retry this exact call. Only when it is false does the user have to add credit at https://porkbun.com/account/credit. Suggest `configure_auto_topup` if they want this to happen automatically next time. Money parameters are integer cents: state amounts to the user in dollars (`cost_cents: 1108` is $11.08). If you do not charge cards on a user's behalf, hand it back instead: tell them the shortfall and that they can add it with **buy account credit** at https://porkbun.com/account/credit, then retry once they have.

Re-queue a past webhook delivery to its endpoint. Clones the delivery into a fresh attempt, reusing the ORIGINAL event id — so a consumer that dedupes on X-Porkbun-Webhook-Id treats the resend as the same event. The endpoint must still exist and be ACTIVE. Use after fixing a downstream bug to replay a delivery that previously FAILED.

Put a domain's DNS zone back to a saved restore point. Call `diff_dns_restore_point` first and show the user what will change. **By default this only ADDS BACK what is missing.** It does not remove records added since — pass prune: true for that, and only after reading the `extra` list, because 'restore my records' usually means 'put back what I lost', not 'delete everything I have done since'. **The restore is itself reversible.** The zone's state from immediately before is saved and returned as `previousStateSavedAs`; restore that id to undo. Use dry_run: true to rehearse — it reports exactly what would change and changes nothing. **Read `failed` in the response.** Parking records and other masked types (ALIAS, HTTPS) are managed by another part of the platform and cannot be recreated this way; they appear in `failed` rather than being counted, so `restored` is always a true number. If a parking record is what is missing, the domain needs re-parking on the website instead. SOA and NS are never touched. **A restore only matters if this zone is the one being served.** If the domain is delegated to another provider, the response carries a `warnings` string saying so: the records went back, and nothing the user can see has changed.

Re-queue a domain whose Cloudflare move failed or was skipped. Fails if it is already connected, already in progress, or no longer in the account — the message says which. Fix the underlying reason first (e.g. disable DNSSEC) or the retry will be skipped again.

UNDO a completed Cloudflare move: point the domain's nameservers back at Porkbun, restoring the DNS Porkbun still holds. This changes authoritative DNS for a live domain, so confirm with the user first. The Cloudflare zone is deliberately LEFT IN PLACE — deleting a zone inside the customer's own Cloudflare account is their call. Fails if Porkbun never moved the domain, it is already back on Porkbun nameservers, or it is being worked on right now.

Generate a new signing secret for a webhook endpoint and return the endpoint with the new secret. Deliveries are signed with the new secret immediately, so update your verifier as part of the same operation.

SANDBOX ONLY. Wipe the sandbox account's simulated state (domains, DNS, orders, credit) and re-grant $1000 fake credit — a clean slate between test runs. Requires a sandbox API key (`pk1_sb_…`). With a live key this endpoint is not available.

SANDBOX ONLY. Grant fake account credit to the sandbox account so paid operations (register/renew/transfer) can keep being exercised after funds run out. Requires a sandbox API key (`pk1_sb_…`). Optional `amount_cents` (integer US cents) (default 100000 = $1000; capped 1,000,000). Returns the new balance. With a live key this endpoint is not available.

SANDBOX ONLY. Fire a sample signed webhook event to your registered endpoints so you can test your handler and HMAC signature verification for ANY event type on demand — including cron-driven events like `domain.expiring` that don't result from a single API call. Register an endpoint first with the webhook tools. Requires a sandbox API key (`pk1_sb_…`).

Discover the DNS records a domain currently publishes by querying its live authoritative nameservers. Writes nothing. Use this before moving a domain to Porkbun: a registrar transfer carries only the delegation, never the zone contents, so the old registrar's records become permanently unreadable the moment it stops answering for the domain — and a domain whose records were never recreated goes dark right then (website down, mail bouncing). Scan first, review, then call import_dns_records, and only then change nameservers. The scan probes a wide list of well-known names (apex, common subdomains, MX, DKIM selectors, provider verification hosts) but cannot enumerate a zone — DNS has no listing operation — so treat it as thorough, not exhaustive, and tell the user that. If the losing registrar has its own API, reading the zone from there is authoritative: do that with the user's own credentials (they must never be sent to Porkbun) and pass the records to import_dns_records instead. Limited to 20 calls per hour per account, since each call is roughly 90 DNS lookups.

Search expired-domain closeouts: names that did not sell at auction and are now offered at a fixed price that descends on a schedule. No bidding — the first buyer at the current price takes the name. Filter by keyword, TLD, exact name length, age range and price range; sort by domain, end time, price, revenue, visitors, inbound links or registration_date. **Every row carries `age` and `registrationDate`, and both are sortable** — sort_name=registrationDate with sort_direction=asc gives the OLDEST registrations first, which is the single most requested thing here and is not possible on the website. Note sort_direction=asc on revenue, visitors or inboundLinks lists the domains with no recorded figure first (they come back null); use desc on those. `price` is the closeout price ALONE. Do not quote a user a total from these results: the binding amount adds the renewal or transfer year and comes from get_closeout. Page with start/limit until start >= totalAvailable.

Keyword-search the full Porkbun API reference and return the most relevant sections (endpoints/topics) as Markdown. Use for 'how do I…' questions — e.g. 'verify a webhook signature', 'register a domain with dry run', 'set a TXT record'. Returns the best-matching sections with their headings; follow up with read_doc for a full topic page. Searches Porkbun's own docs only.

Turn the Cloudflare proxy (orange cloud) on or off for a domain's DNS records. NOTE: connecting a domain deliberately imports every record DNS-only (grey cloud), because changing how traffic is served at the same time as changing who serves DNS makes failures hard to diagnose — so proxying is a separate, explicit step, best done AFTER confirming the site still works. Defaults to every proxiable record; pass `records` to target specific names ("@" = apex, bare labels like "www" are expanded). Only A/AAAA/CNAME can be proxied; anything else comes back under `skipped` with a reason rather than failing. Proxying hides the origin IP, so if MX points at a name you're proxying, mail to it breaks — that comes back in `warnings`. Reversible: call again with enabled=false. Use dry_run to preview.

Change Cloudflare zone settings for a moved domain. Only an allowlist is editable (ssl, always_use_https, automatic_https_rewrites, min_tls_version, development_mode, cache_level) — WAF/firewall/security controls are deliberately not exposed. Prefer ssl `full` over `flexible`: `flexible` makes Cloudflare fetch the origin over plain HTTP, a downgrade the visitor cannot see. CLOUDFLARE_REAUTHORIZE_REQUIRED means the stored authorization lacks this permission — surface the connectUrl and ask the customer to reconnect. Supports dry_run.

Release a held inbound transfer to the registry. Final step of the no-downtime sequence, and the only thing that releases a hold — nothing does it on a timer, so a held transfer waits indefinitely until you call this. Refuses with TRANSFER_ZONE_EMPTY if the zone has no records, which is the outage the hold exists to prevent; only pass force when the domain genuinely needs no DNS at Porkbun.

Send a `webhook.test` event to an endpoint to confirm it's reachable and that signature verification works. The endpoint must be ACTIVE. Delivery happens asynchronously (usually within a minute); check the endpoint's last_success_date via get_webhook afterward.

**Charges the user's saved payment method** (`amount_cents` is integer cents: 803 charges $8.03; tell the user the dollar figure first) and adds the money to their Porkbun account credit immediately. Use it when a purchase failed with INSUFFICIENT_FUNDS and the user wants to continue now — enabling auto top-up does not help in that moment, because it only fires on the next order. **Ask the user before calling, with the figure. This spends real money off a card, not credit they already bought.** Omit `amount_cents` and it charges what the account has configured (or $50 if it never has) — that is the right default, and `amount_source` in the response says which was used. Pass `amount_cents` only when the user wants a specific one-off figure, e.g. enough to cover a particular purchase; it does NOT change their saved setting, so prefer it over calling `configure_auto_topup` for a single charge. Fails with `NO_PAYMENT_METHOD` when nothing is saved to charge (the user has to save a card or buy credit on porkbun.com; the API cannot add one), `CARD_DECLINED` when the card refuses, and `TOPUP_LIMIT_EXCEEDED` when the month's dollars or the frequency run out — the account's monthly spend limit caps top-up dollars as well as domain spend, an account with no limit set gets $100/month, and there are 5/day and 20/month count caps. `get_auto_topup` reports `monthlyCeiling`, `ceilingSource` and `toppedUpThisMonth`, so check there before promising a user a top-up will go through. Every successful charge emails the account holder. A sandbox key grants simulated credit and charges nothing. Supports dry_run, which previews and charges nothing.

**Spends account credit.** Initiates a transfer of an external domain into Porkbun. Requires the auth/EPP code from the losing registrar, and `cost_cents` must match the current transfer price from `check_domain`. Poll with `get_transfer_status`. Most transfers finish well inside the five-day worst case — two thirds within 24 hours — so do not promise the user a week. .uk and a few TLDs do not support inbound API transfers. Idempotency-safe. **Set `hold_for_dns_setup` unless the user has no DNS to preserve.** A transfer carries only the delegation, so a domain that moves before its records exist at Porkbun goes dark. Holding charges the transfer but parks it until you release it: hold → prepare_transfer → import_dns_records → start_transfer. Nothing releases a held transfer on a timer. **Money comes from prepaid account credit.** The purchase itself charges the credit balance, never a card. If the balance is short, the call fails with `INSUFFICIENT_FUNDS` carrying `cost`, `balance`, `shortfall` and **`topUpAvailable`** (`dry_run: true` reports the same without charging). When `topUpAvailable` is true a card is saved: tell the user the shortfall and offer to top up — with their OK, call `top_up_account_credit` (`amount_cents` at least `topUpAmountToCover`, or omit it for their configured amount) and then retry this exact call. Only when it is false does the user have to add credit at https://porkbun.com/account/credit. Suggest `configure_auto_topup` if they want this to happen automatically next time. Money parameters are integer cents: state amounts to the user in dollars (`cost_cents: 1108` is $11.08). If you do not charge cards on a user's behalf, hand it back instead: tell them the shortfall and that they can add it with **buy account credit** at https://porkbun.com/account/credit, then retry once they have.

Turn auto-renewal on or off for a domain in the authenticated account. When auto-renew is on, Porkbun automatically charges your account credit at expiration. When off, you must manually renew or the domain expires. Idempotent.

Edit a domain's contacts. Provide `contacts` keyed by role with ANY subset of registrant/admin/tech/billing (unspecified roles keep their current values), or a single `contact` applied to all four. Mirrors the website: pushes to the registry on thick TLDs, and a registrant change (name/organization/email) fires the same new-owner notice/verification email — no 60-day transfer lock. Supports `dry_run`. Note: a registrant name/organization change on a .au domain, or any registrant change on an address-validation TLD (.de/.nrw), is rejected with REGISTRANT_CHANGE_NOT_SUPPORTED — do those at porkbun.com; admin/tech/billing edits still work.

Update an existing DNS record by its numeric `record_id` (obtained from `list_dns_records`). All fields except `record_id` and `domain` are optional — pass only the ones you want to change. Idempotent: applying the same update twice is a no-op. **Check `warnings` in the response and pass it on.** Porkbun keeps a DNS zone for every domain in the account whether or not the domain is delegated to Porkbun's nameservers, so this write succeeds either way. If the domain points somewhere else, the response is still `SUCCESS` but carries a `warnings` string naming the nameservers that actually answer — the record exists and nothing resolves differently. Do not report plain success in that case: either make the change at the provider that runs those nameservers, or offer `update_nameservers` to point the domain at Porkbun.

Update the IP addresses associated with an existing glue record. Replaces the full IP list — pass all IPs you want set, not just additions. Idempotent.

Replace the nameservers for a domain in the authenticated account. **This is a full replacement, not an append** — the supplied list becomes the complete set of nameservers. Most TLDs require 2-13 entries. Setting custom nameservers disables Porkbun's free DNS hosting for the domain. Idempotent: applying the same NS list twice is a no-op. The list is applied as a set — the registry may return it in a different order, so do not expect `get_nameservers` to echo your ordering back, and do not treat a reordering as drift.

Replace the authorization code on an inbound transfer that stalled because the code was wrong, and re-queue it — instead of cancelling, refunding and resubmitting. The new code is validated against the registry before being stored, so a bad one is rejected here rather than failing again days later. Only repairable transfers qualify; others return TRANSFER_NOT_REPAIRABLE. Note that a losing registrar's refusal also surfaces as a bad-auth-code status, so check for a denial notice before assuming the code is the problem.

Update a webhook endpoint. Only the supplied fields change. Set `status` to `DISABLED` to pause deliveries or `ACTIVE` to resume (resuming also clears the consecutive-failure counter). A replacement `url` must satisfy the same public-HTTPS rules as create_webhook. Idempotent. Calls the Porkbun Webhooks API (https://porkbun.com/llms/webhooks).