Connecting to the DreamHost API

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

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.

1. Visit the API page in your panel.
2. This page lists all API functions available. Only the functions you check will be available to you when using the key. If you wish to have all services available, check All functions! at the top.
3. Click Genereate 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.

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.

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

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.

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 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 [email protected], this variable would be testlist.
• The DOMAIN is the URL the list appears on. If the List Name was [email protected] 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