API Documentation - Version 3 - Beta

General API Information

Overview
API Hostname
IPv4 Only API Hostname
Domain Pricing
Authentication
Errors
Example Code

Domain Functionality

Domain Update Name Servers
Domain Get Name Servers
Domain List All
Domain Add Url Forward
Domain Get URL Forwarding
Domain Delete Url Forward

DNS Functionality

DNS Create Record
DNS Edit Record by Domain and ID
DNS Edit Records by Domain, Subdomain and Type
DNS Delete Record by Domain and ID
DNS Delete Records by Domain, Subdomain and Type
DNS Retrieve Records by Domain or ID
DNS Retrieve Records by Domain, Subdomain and Type

SSL Functionality

SSL Retrieve Bundle by Domain

Overview

The Porkbun API uses JSON content sent to URI endpoints via HTTP POST. Functionality is currently limited but as more functionality is added it will be documented here.

Please note that values in URI examples surrounded by brackets, [SUBDOMAIN] for example, are optional.

API Hostname

api.porkbun.com

Please note that porkbun.com currently works and has historically been the correct hostname for our API. However, we will be migrating away from that hostname and the API will no longer be available using it after 2024-12-01 00:00:00 UTC.

IPv4 Only Hostname

Some folks prefer to force IPv4, especially when using the ping command to get back an IP address for dynamic DNS clients. The dedicated IPv4 hostname is api-ipv4.porkbun.com, use this instead of porkbun.com.

Domain Pricing

Check default domain pricing information for all supported TLDs. This command does not require authentication.

Command Element Descriptions

None

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.
pricing
Objects with default pricing for the registration, renewal and transfer of each supported TLD.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/pricing/get

JSON Command
None
JSON Response
{ "status": "SUCCESS", "pricing": { "design": { "registration": "35.58", "renewal": "35.58", "transfer": "35.58" }, "com": { "registration": "9.68", "renewal": "9.68", "transfer": "9.68" }, ... } }

Authentication

Authentication is done by passing an API key and secret API key in the JSON content posted to the URI endpoint. All API calls must include valid API keys. You can create API keys at porkbun.com/account/api. You can test communication with the API using the ping endpoint. The ping endpoint will also return your IP address, this can be handy when building dynamic DNS clients.

Get API Key

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/ping

JSON Command Example
{ "secretapikey": "YOUR_SECRET_API_KEY", "apikey": "YOUR_API_KEY" }
JSON Response Example
{ "status": "SUCCESS", "yourIp": "3.146.37.242" }

Errors

Any HTTP response code other than 200 is an error. Errors will also be indicated in the "status" element of the returned JSON. An HTTP response of 403 means that additional authentication information is required, such as a two factor code.

Example

JSON Response Example

{
	"status": "ERROR",
	"message": "All HTTP request must use POST."
}

Examples

Knowledge based article with sample applications demonstrating use of the DNS management API:

Getting started with the Porkbun DNS API

Domain Update Name Servers

Update the name servers for your domain.

Command Element Descriptions

secretapikey
Your secret API key.
apikey
Your API key.
ns
An array of name servers that you would like to update your domain with.

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/domain/updateNs/DOMAIN

URI Endpoint Example: https://api.porkbun.com/api/json/v3/domain/updateNs/borseth.ink

JSON Command Example
{ "secretapikey": "YOUR_SECRET_API_KEY", "apikey": "YOUR_API_KEY", "ns": [ "ns1.example.com", "ns2.example.com" ] }
JSON Response Example
{ "status": "SUCCESS" }

Domain Get Name Servers

Get the authoritative name servers listed at the registry for your domain.

Command Element Descriptions

secretapikey
Your secret API key.
apikey
Your API key.

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.
ns
An array of name server host names.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/domain/getNs/DOMAIN

URI Endpoint Example: https://api.porkbun.com/api/json/v3/domain/getNs/borseth.ink

JSON Command Example
{ "secretapikey": "YOUR_SECRET_API_KEY", "apikey": "YOUR_API_KEY" }
JSON Response Example
{ "status": "SUCCESS", "ns": [ "curitiba.ns.porkbun.com", "fortaleza.ns.porkbun.com", "maceio.ns.porkbun.com", "salvador.ns.porkbun.com" ] }

Domain List All

Get all domain names in account. Domains are returned in chunks of 1000.

Command Element Descriptions

secretapikey
Your secret API key.
apikey
Your API key.
start - optional
An index to start at when retrieving the domains, defaults to 0. To get all domains increment by 1000 until you receive an empty array.
includeLabels - optional
If set to "yes" we will return label information for the domains if it exists.

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.
domains
An array of domains and domain details in the account.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/domain/listAll

URI Endpoint Example: https://api.porkbun.com/api/json/v3/domain/listAll

JSON Command Example
{ "secretapikey": "YOUR_SECRET_API_KEY", "apikey": "YOUR_API_KEY", "start": "1", "includeLabels": "yes" }
JSON Response Example
{ "status": "SUCCESS", "domains": [ { "domain": "borseth.ink", "status": "ACTIVE", "tld": "app", "createDate": "2018-08-20 17:52:51", "expireDate": "2023-08-20 17:52:51", "securityLock": "1", "whoisPrivacy": "1", "autoRenew": 0, "notLocal": 0, "labels": [ { "id": "27240", "title": "cool", "color": "#ff9e9e" }, { "id": "27241", "title": "silly", "color": "#f00000" } ] } ] }

Domain Add URL Forward

Add URL forward for a domain.

Command Element Descriptions

secretapikey
Your secret API key.
apikey
Your API key.
subdomain - optional
A subdomain that you would like to add URL forwarding for. Leave this blank to forward the root domain.
location
Where you'd like to forward the domain to.
type
The type of forward. Valid types are: temporary or permanent
includePath
Whether or not to include the URI path in the redirection. Valid options are yes or no.
wildcard
Also forward all subdomains of the domain. Valid options are yes or no.

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/domain/addUrlForward/DOMAIN

URI Endpoint Example: https://api.porkbun.com/api/json/v3/domain/addUrlForward/borseth.ink

JSON Command Example
{ "secretapikey": "YOUR_SECRET_API_KEY", "apikey": "YOUR_API_KEY", "subdomain": "", "location": "https://porkbun.com", "type": "temporary", "includePath": "no", "wildcard": "yes" }
JSON Response Example
{ "status": "SUCCESS" }

Domain Get URL Forwarding

Get URL forwarding for a domain.

Command Element Descriptions

secretapikey
Your secret API key.
apikey
Your API key.

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.
forwards
An array of forwarding records for the domain.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/domain/getUrlForwarding/DOMAIN

URI Endpoint Example: https://api.porkbun.com/api/json/v3/domain/getUrlForwarding/borseth.ink

JSON Command Example
{ "secretapikey": "YOUR_SECRET_API_KEY", "apikey": "YOUR_API_KEY" }
JSON Response Example
{ "status": "SUCCESS", "forwards": [ { "id": "22049216", "subdomain": "", "location": "https://porkbun.com", "type": "temporary", "includePath": "no", "wildcard": "yes" }, { "id": "22049209", "subdomain": "blog", "location": "https://blog.porkbun.com", "type": "temporary", "includePath": "no", "wildcard": "yes" } ] }

Domain Delete URL Forward

Delete a URL forward for a domain.

Command Element Descriptions

secretapikey
Your secret API key.
apikey
Your API key.

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/domain/deleteUrlForward/DOMAIN/RECORD ID

URI Endpoint Example: https://api.porkbun.com/api/json/v3/domain/deleteUrlForward/borseth.ink/22049209

JSON Command Example
{ "secretapikey": "YOUR_SECRET_API_KEY", "apikey": "YOUR_API_KEY" }
JSON Response Example
{ "status": "SUCCESS" }

DNS Create Record

Create a DNS record.

Command Element Descriptions

secretapikey
Your secret API key.
apikey
Your API key.
name - optional
The subdomain for the record being created, not including the domain itself. Leave blank to create a record on the root domain. Use * to create a wildcard record.
type
The type of record being created. Valid types are: A, MX, CNAME, ALIAS, TXT, NS, AAAA, SRV, TLSA, CAA, HTTPS, SVCB
content
The answer content for the record. Please see the DNS management popup from the domain management console for proper formatting of each record type.
ttl - optional
The time to live in seconds for the record. The minimum and the default is 600 seconds.
prio - optional
The priority of the record for those that support it.

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.
id
The ID of the record created.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/dns/create/DOMAIN

URI Endpoint Example: https://api.porkbun.com/api/json/v3/dns/create/borseth.ink

JSON Command Example
{ "secretapikey": "YOUR_SECRET_API_KEY", "apikey": "YOUR_API_KEY", "name": "www", "type": "A", "content": "1.1.1.1", "ttl": "600" }
JSON Response Example
{ "status": "SUCCESS", "id": "106926659" }

DNS Edit Record by Domain and ID

Edit a DNS record.

Command Element Descriptions

secretapikey
Your secret API key.
apikey
Your API key.
name - optional
The subdomain for the record being created, not including the domain itself. Leave blank to create a record on the root domain. Use * to create a wildcard record.
type
The type of record being created. Valid types are: A, MX, CNAME, ALIAS, TXT, NS, AAAA, SRV, TLSA, CAA, HTTPS, SVCB
content
The answer content for the record. Please see the DNS management popup from the domain management console for proper formatting of each record type.
ttl - optional
The time to live in seconds for the record. The minimum and the default is 600 seconds.
prio - optional
The priority of the record for those that support it.

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/dns/edit/DOMAIN/ID

URI Endpoint Example: https://api.porkbun.com/api/json/v3/dns/edit/borseth.ink/106926659

JSON Command Example
{ "secretapikey": "YOUR_SECRET_API_KEY", "apikey": "YOUR_API_KEY", "name": "www", "type": "A", "content": "1.1.1.2", "ttl": "600" }
JSON Response Example
{ "status": "SUCCESS" }

DNS Edit Record by Domain, Subdomain and Type

Edit all records for the domain that match a particular subdomain and type.

Command Element Descriptions

secretapikey
Your secret API key.
apikey
Your API key.
content
The answer content for the record. Please see the DNS management popup from the domain management console for proper formatting of each record type.
ttl - optional
The time to live in seconds for the record. The minimum and the default is 600 seconds.
prio - optional
The priority of the record for those that support it.

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/dns/editByNameType/DOMAIN/TYPE/[SUBDOMAIN]

URI Endpoint Example: https://api.porkbun.com/api/json/v3/dns/editByNameType/borseth.ink/A/www

JSON Command Example
{ "secretapikey": "YOUR_SECRET_API_KEY", "apikey": "YOUR_API_KEY", "content": "1.1.1.2", "ttl": "600" }
JSON Response Example
{ "status": "SUCCESS" }

DNS Delete Record by Domain and ID

Delete a specific DNS record.

Command Element Descriptions

secretapikey
Your secret API key.
apikey
Your API key.

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/dns/delete/DOMAIN/ID

URI Endpoint Example: https://api.porkbun.com/api/json/v3/dns/delete/borseth.ink/106926659

JSON Command Example
{ "secretapikey": "YOUR_SECRET_API_KEY", "apikey": "YOUR_API_KEY" }
JSON Response Example
{ "status": "SUCCESS" }

DNS Delete Records by Domain, Subdomain and Type

Delete all records for the domain that match a particular subdomain and type.

Command Element Descriptions

secretapikey
Your secret API key.
apikey
Your API key.

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/dns/deleteByNameType/DOMAIN/TYPE/[SUBDOMAIN]

URI Endpoint Example: https://api.porkbun.com/api/json/v3/dns/deleteByNameType/borseth.ink/A/www

JSON Command Example
{ "secretapikey": "YOUR_SECRET_API_KEY", "apikey": "YOUR_API_KEY" }
JSON Response Example
{ "status": "SUCCESS" }

DNS Retrieve Records by Domain or ID

Retrieve all editable DNS records associated with a domain or a single record for a particular record ID.

Command Element Descriptions

secretapikey
Your secret API key.
apikey
Your API key.

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.
records
An array of DNS records.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/dns/retrieve/DOMAIN/ID
URI Endpoint w/ ID: https://api.porkbun.com/api/json/v3/dns/retrieve/DOMAIN/ID

URI Endpoint Example: https://api.porkbun.com/api/json/v3/dns/retrieve/borseth.ink
URI Endpoint Example w/ ID: https://api.porkbun.com/api/json/v3/dns/retrieve/borseth.ink/106926652

JSON Command Example
{ "secretapikey": "YOUR_SECRET_API_KEY", "apikey": "YOUR_API_KEY" }
JSON Response Example
{ "status": "SUCCESS", "records": [ { "id": "106926652", "name": "borseth.ink", "type": "A", "content": "1.1.1.1", "ttl": "600", "prio": "0", "notes": "" }, { "id": "106926659", "name": "www.borseth.ink", "type": "A", "content": "1.1.1.1", "ttl": "600", "prio": "0", "notes": "" } ] } JSON Response Example w/ ID
{ "status": "SUCCESS", "records": [ { "id": "106926652", "name": "borseth.ink", "type": "A", "content": "1.1.1.1", "ttl": "600", "prio": "0", "notes": "" } ] }

DNS Retrieve Records by Domain, Subdomain and Type

Retrieve all editable DNS records associated with a domain, subdomain and type.

Command Element Descriptions

secretapikey
Your secret API key.
apikey
Your API key.

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.
records
An array of DNS records.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/dns/retrieveByNameType/DOMAIN/TYPE/[SUBDOMAIN]

URI Endpoint Example: https://api.porkbun.com/api/json/v3/dns/retrieveByNameType/borseth.ink/A/www

SSL Retrieve Bundle by Domain

Retrieve the SSL certificate bundle for the domain.

Command Element Descriptions

secretapikey
Your secret API key.
apikey
Your API key.

Response Element Descriptions

status
A status indicating whether or not the command was successfuly processed.
certificatechain
The complete certificate chain.
privatekey
The private key.
publickey
The public key.

Example

URI Endpoint: https://api.porkbun.com/api/json/v3/ssl/retrieve/DOMAIN

URI Endpoint Example: https://api.porkbun.com/api/json/v3/ssl/retrieve/borseth.ink

JSON Command Example
{ "secretapikey": "YOUR_SECRET_API_KEY", "apikey": "YOUR_API_KEY" }
JSON Response Example
{ "status": "SUCCESS", "certificatechain": "----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n\n----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n\n----BEGIN CERTIFICATE-----\n...-----END CERTIFICATE-----\n", "privatekey": "-----BEGIN PRIVATE KEY-----\n...-----END PRIVATE KEY-----\n", "publickey": "-----BEGIN PUBLIC KEY-----\n...-----END PUBLIC KEY-----\n" }