Overview
This article explains how to create a call to access the DreamHost API. You can use DreamHost's API in two ways:
- Visiting a URL in your browser
- Writing a script
Connecting to the API
An API call is constructed of several values. The following steps walk you through creating an API call using these values.
Step 1 — The base URL
The base URL is the same for all API calls. It is:
https://api.dreamhost.com
Everything you add after this URL creates your own unique API call.
Step 2 — Generate an API key
You must first create an API Key. This is a unique key associated with your account and the information you wish to make available to any API call.
- Visit the API page in your panel.
- This page lists all API functions available. Only the functions you check will be available to you when using the key.
- Check All functions! at the top if you wish to have all services available.
- Click Generate a new API Key now! at the bottom to create your key.
Your new key is displayed. You can now use this key to connect with the DreamHost API.
In order for a subaccount to create an API Key, it must be granted Billing Account Privileges.
Please note that if a subaccount creates an API Key, it will only be visible to the subaccount on the API Key page in the panel. The primary account owner will not be able to view the subaccount's API Key in their panel.
After the base URL, add ?key= followed by the key. Assuming your API Key is 1A2B3C4D5E6F7G8H, the first part of your API call will look like this:
https://api.dreamhost.com/?key=1A2B3C4D5E6F7G8H
Step 3 — Add the Command
The API Key is followed by the specific API command you'd like to run. When you created your key, you chose which command(s) it may access. You can find the different commands on the various API pages.
In this example, the command to list all DNS records on an account is used.
This command is dns-list_records.
After the API Key, add &cmd= followed by the command.
https://api.dreamhost.com/?key=1A2B3C4D5E6F7G8H&cmd=dns-list_records
This simple command is all you need to interact with the API. If you visit the URL above in a browser, you'll see a response.
There are additional commands you can add to manage and format the response.
Step 4 — Add values
Not all API calls require specific values. View the API page for the command you're running to confirm which fields are necessary.
Some API calls require you to specify a value. For example, if you want to add a DNS record to a domain using dns-add_record, you must specify the following values:
- record: &record= followed by the domain name
- type: &type= followed by the type of DNS record
- value: &value= followed by the DNS value to add
The following example would add a TXT record with the value of test123 to example.com.
https://api.dreamhost.com/?key=1A2B3C4D5E6F7G8H&cmd=dns-add_record&record=example.com&type=TXT&value=test123
Step 5 — Choose a format (optional)
When you make a call to the API, the response is returned in a specific format. You can choose which type of format you want the data to be returned in by adding &format= followed by the format. Valid formats are:
The following returns data in JSON format:
https://api.dreamhost.com/?key=1A2B3C4D5E6F7G8H&cmd=account-domain_usage&format=json
Step 6 — Add a unique ID to the call (optional)
You may pass a new unique id value (max length: 64 chars) when you submit a request to ensure you do not accidentally submit the same command twice. This is most useful when creating a script to run the commands.
DreamHost recommends using UUIDs for this purpose, but any values will work. The unique id you use only applies to your specific API key, so you do not need to worry about other users using the same unique id.
Only successful queries "use up" a unique_id.
To add a unique id, add &unique_id= followed by the id value. For example, the id value of 123456 is used in the following example:
https://api.dreamhost.com/?key=1A2B3C4D5E6F7G8H&cmd=dnslist_records&format=json&unique_id=123456
Step 7 — Add your account # (optional)
You can also add the account number you intend to perform operations under. You can specify this by adding &account= followed by the account number on the Manage Account page. For example:
https://api.dreamhost.com/?key=1A2B3C4D5E6F7G8H&cmd=account-domain_usage&format=json&account=123456
The account automatically defaults to your own, or the first account you have access to.
Connecting using a script
The following is a simple Bash script that prints all subscribers to a specific Announcement List.
- This uses the command announcement_list-list_subscribers.
- The LISTNAME variable is the first part of the List Name found on the Announce Lists page. If the List Name was testlist@example.com, this variable would be testlist.
- The DOMAIN is the URL the list appears on. If the List Name was testlist@example.com this variable would be example.com.
#!/bin/bash # variables KEY=1A2B3C4D5E6F7G8H CMD=announcement_list-list_subscribers FORMAT=json LISTNAME=testlist DOMAIN=example.com # commands LINK="https://api.dreamhost.com/?key=$KEY&cmd=$CMD&format=$FORMAT&listname=$LISTNAME&domain=$DOMAIN" RESPONSE=`wget -O- -q "$LINK" | python -m json.tool` # print results echo "$LINK" echo "$RESPONSE" if ! (echo $RESPONSE | grep -q 'success'); then exit 1 fi