# Porkbun

> Porkbun is a domain registrar with a developer-friendly REST API for programmatic domain registration, DNS management, SSL certificates, and related operations.

Porkbun's API is designed to be fully usable by AI agents and automation tools. It supports header-based authentication, GET requests on all read-only endpoints, machine-readable error codes, and rate limit state via response headers. The OpenAPI spec is available at https://porkbun.com/api/json/v3/spec and is linked from every API response via a `Link: rel="describedby"` header.

## What you can do with the Porkbun API

- Check domain availability and pricing across hundreds of TLDs (no authentication required)
- Register domain names programmatically
- List and manage all domains in an account
- Create, read, update, and delete DNS records (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, TLSA, SSHFP, ALIAS)
- Manage DNSSEC records
- Retrieve free SSL certificate bundles for registered domains
- Configure URL forwarding and redirects
- Manage glue records for custom nameservers
- Set auto-renewal preferences across a domain portfolio
- Detect caller IP address (useful for dynamic DNS clients)

## Quickstart (agentic domain registration)

1. Check availability: `GET https://api.porkbun.com/api/json/v3/domain/checkDomain/{domain}` with `X-API-Key` / `X-Secret-API-Key` headers
2. Register: `POST /domain/create/{domain}` with `cost` (price in pennies as integer), `agreeToTerms: "yes"`
3. Add DNS: `POST /dns/create/{domain}` with `type`, `content`, optional `ttl`

## Common agentic use cases

- **Agentic domain registration**: Search availability with `/domain/checkDomain/{domain}`, then register with `/domain/create/{domain}`
- **Dynamic DNS**: `GET /ping` or `GET /ip` to detect IP changes, update records with `/dns/editByNameType/{domain}/{type}/{subdomain}`
- **Infrastructure automation**: Provision DNS records on deployment, tear them down on teardown
- **Domain portfolio management**: Page through all domains with `GET /domain/listAll?start=0`, monitor expiry dates, toggle auto-renewal

## Authentication

Pass `apikey` and `secretapikey` in the JSON request body, or use `X-API-Key` and `X-Secret-API-Key` request headers (preferred for GET requests and agent frameworks). Header auth takes effect when no body credentials are present.

API keys: https://porkbun.com/account/api

## Key endpoints

- `GET/POST /ping` — Verify credentials and get caller IP (credentials optional)
- `GET/POST /ip` — Get caller IP, no auth required
- `GET/POST /pricing/get` — Domain pricing across all TLDs (no auth)
- `POST /domain/checkDomain/{domain}` — Check availability and price
- `POST /domain/create/{domain}` — Register a domain
- `GET/POST /domain/listAll` — List all domains (paginate with `?start=N`, 1000 per page)
- `GET/POST /dns/retrieve/{domain}` — Get DNS records
- `POST /dns/create/{domain}` — Create a DNS record
- `POST /dns/edit/{domain}/{id}` — Update a DNS record by ID
- `POST /dns/editByNameType/{domain}/{type}/{subdomain}` — Update records by name and type
- `POST /dns/delete/{domain}/{id}` — Delete a DNS record
- `GET/POST /ssl/retrieve/{domain}` — Get SSL certificate bundle

## Error codes

Every error response includes `status: "ERROR"`, a human-readable `message`, and a machine-readable `code`. Key codes:

- `INVALID_API_KEYS_001` — invalid API key/secret
- `RATE_LIMIT_EXCEEDED` — rate limit hit; check `ttlRemaining` and `X-RateLimit-Reset`
- `INVALID_DOMAIN` — domain not valid or not in your account
- `DOMAIN_NOT_AVAILABLE` — domain cannot be registered
- `INSUFFICIENT_FUNDS` — not enough account credit
- `INVALID_TYPE` — unsupported DNS record type

## Agent-friendly features

- Machine-readable `code` field on all error responses
- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers on rate-limited endpoints
- `Link: <https://porkbun.com/api/json/v3/spec>; rel="describedby"` on every API response
- GET method supported on all read-only endpoints
- Header-based auth (`X-API-Key`, `X-Secret-API-Key`) compatible with standard agent frameworks
- Query string parameters supported on GET endpoints (e.g. `?start=1000` for pagination)

## API specification

- OpenAPI 3.0 spec: https://porkbun.com/api/json/v3/spec
- Interactive docs: https://porkbun.com/api/json/v3/documentation
- Base URL: https://api.porkbun.com/api/json/v3
- IPv4-only base URL: https://api-ipv4.porkbun.com/api/json/v3 (use when a client on an IPv6 network needs to force IPv4)

## Links

- Homepage: https://porkbun.com
- Domain pricing: https://porkbun.com/tlds
- Create API keys: https://porkbun.com/account/api
- Support: https://porkbun.com/support