API Reference

The WebFaction XML-RPC API provides methods to make many account tasks scriptable. This documentation is a complete reference to all of the possible API methods.

Please note that XML-RPC parameters are positional (order matters), and many parameters are required. Parameters may only be omitted if omitted parameters have default values and follow all other parameters to which you have supplied a value.

General

login
Parameters:
  • username (string) – a valid WebFaction control panel username
  • password (string) – a valid WebFaction control panel user’s password
  • machine (string) – the case-sensitive machine name (for example, Web55); optional for accounts with only one machine

Log in a user and return credentials required to make requests for that user. The method returns a session ID string and a struct containing following key-value pairs:

id
account ID
username
username
home
home directory path
web_server
Web server associated with the logged in account (for example, Web55)
mail_server
mail server associated with the logged in account (for example, Mailbox2)

Note

The session ID is required for all subsequent API calls.

list_disk_usage
Parameters:session_id – session ID returned by login

List disk space usage statistics about your account (similar to usage statistics shown on the control panel). The method returns a struct containing the following members:

home_directories

A list of structs with details for each home directory associated with the account. Each struct contains the following members:

last_reading
The date and time of the last recording of the home directory’s size
machine
The server name (for example, Web300)
name
The username
size
The disk usage in kilobytes
mailboxes

A list of structs with details for each mailbox associated with the account. Each struct contains the following members:

last_reading
The date and time of the last recording of the mailbox’s size
name
The mailbox name
size
The disk usage in kilobytes
mysql_databases

A list of structs with details for each MySQL database associated with the account. Each struct contains the following members:

last_reading
The date and time of the last recording of the database’s size
name
The database name
size
The disk usage in kilobytes
postgresql_databases

A list of structs with details for each PostgreSQL database associated with the account. Each struct contains the following members:

last_reading
The date and time of the last recording of the database’s size
name
The database name
size
The disk usage in kilobytes
total
The account’s total disk usage in kilobytes
quota
The account’s total disk allotment in kilobytes
percentage
The account’s total disk usage as a percentage of the quota (for example, an account using 3.1 GB of 100 GB would use 3.1 percent of its quota)

Email

Mailboxes

change_mailbox_password
Parameters:
  • session_id – session ID returned by login
  • mailbox (string) – a valid mailbox name
  • password (string) – the new mailbox password

Change a mailbox password.

See also

See Strengthening Passwords for important information about choosing passwords.

create_mailbox
Parameters:
  • session_id – session ID returned by login
  • mailbox (string) – mailbox name
  • enable_spam_protection (boolean) – whether spam protection is enabled for the mailbox (optional, default: true)
  • discard_spam (boolean) – whether spam messages received by the new mailbox are discarded (optional, default: false)
  • spam_redirect_folder (string) – name of the IMAP folder where messages identified as spam are stored (optional, default: an empty string)
  • use_manual_procmailrc (boolean) – whether to use manual procmailrc rules as specified by the manual_procmailrc parameter (optional, default: false)
  • manual_procmailrc (string) – the procmailrc rules for the mailbox (optional, default: an empty string)

Warning

If discard_spam is true, messages misidentified as spam—false positives—may be lost permanently.

Create a mailbox and return a struct containing the following key-value pairs:

id
mailbox ID
name
mailbox name
enable_spam_protection
name of the folder where messages identified as spam are stored
password
a randomly generated password
discard_spam
a boolean indicating whether spam emails are be discarded
spam_redirect_folder
name of the IMAP folder where messages identified as spam are stored
use_manual_procmailrc
a boolean indicating whether manual procmailrc rules are enabled
manual_procmailrc
a string containing manual procmailrc rules

See also

update_mailbox

delete_mailbox
Parameters:
  • session_id – session ID returned by login
  • mailbox (string) – mailbox name

Delete a mailbox.

list_mailboxes
Parameters:session_id – session ID returned by login

Get information about the account’s mailboxes. The method returns an array of structs with the following key-value pairs:

id
mailbox ID
name
mailbox name
enable_spam_protection
name of the folder where messages identified as spam are stored
password
a randomly generated password
discard_spam
a boolean indicating whether spam emails are be discarded
spam_redirect_folder
name of the IMAP folder where messages identified as spam are stored
use_manual_procmailrc
a boolean indicating whether manual procmailrc rules are enabled
manual_procmailrc
a string containing manual procmailrc rules
update_mailbox
Parameters:
  • session_id – session ID returned by login
  • mailbox (string) – mailbox name
  • enable_spam_protection (boolean) – whether spam protection is enabled for the mailbox (optional, default: true)
  • discard_spam (boolean) – whether spam messages received by the new mailbox are discarded (optional, default: false)
  • spam_redirect_folder (string) – name of the IMAP folder where messages identified as spam are stored (optional, default: an empty string)
  • use_manual_procmailrc (boolean) – whether to use manual procmailrc rules as specified by the manual_procmailrc parameter (optional, default: false)
  • manual_procmailrc (string) – the procmailrc rules for the mailbox (optional, default: an empty string)

Warning

If discard_spam is true, messages misidentified as spam—false positives—may be lost permanently.

Change the details of an existing mailbox. The mailbox must exist before calling the method. The method returns a struct containing the following key-value pairs:

id
mailbox ID
name
mailbox name
enable_spam_protection
name of the folder where messages identified as spam are stored
password
a randomly generated password
discard_spam
a boolean indicating whether spam emails are be discarded
spam_redirect_folder
name of the IMAP folder where messages identified as spam are stored
use_manual_procmailrc
a boolean indicating whether manual procmailrc rules are enabled
manual_procmailrc
a string containing manual procmailrc rules

See also

create_mailbox

Addresses

create_email
Parameters:
  • session_id – session ID returned by login
  • email_address (string) – an email address (for example, name@example.com)
  • targets (string) – names of destination mailboxes or addresses, separated by commas
  • autoresponder_on (boolean) – whether an autoresponder is enabled for the address (optional, default: false)
  • autoresponder_subject (string) – subject line of the autoresponder message (optional, default: an empty string)
  • autoresponder_message (string) – body of the autoresponder message (optional, default: an empty string)
  • autoresponder_from (string) – originating address of the autoresponder message (optional, default: an empty string)
  • script_machine (string) – a machine name for specifying a path to a script (optional, default: an empty string)
  • script_path (string) – an absolute path to a script; see Sending Mail to a Script for details (optional, default: an empty string)

Create an email address which delivers to the specified mailboxes.

If autoresponder_on is true, then an autoresponder subject, message, and from address may be specified.

See also

update_email

delete_email
Parameters:
  • session_id – session ID returned by login
  • email_address (string) – an email address (for example, name@example.com)

Delete an email address.

list_emails
Parameters:session_id – session ID returned by login

Get information about the account’s email addresses. The method returns an array of structs with the following key-value pairs:

id
email ID
email_address
email address
targets
mailboxes or email addresses to which the address is set to deliver
autoresponder_on
a boolean indicating whether an autoresponder is enabled for the address
autoresponder_subject
the autoresponder subject line (if applicable)
autoresponder_message
the autoresponder message body (if applicable)
autoresponder_from
the autoresponder from address (if applicable)
update_email
Parameters:
  • session_id – session ID returned by login
  • email_address (string) – an email address (for example, name@example.com)
  • targets (array) – names of destination mailboxes or addresses
  • autoresponder_on (boolean) – whether an autoresponder is enabled for the address (optional, default: false)
  • autoresponder_subject (string) – subject line of the autoresponder message (optional, default: an empty string)
  • autoresponder_message (string) – body of the autoresponder message (optional, default: an empty string)
  • autoresponder_from (string) – originating address of the autoresponder message (optional, default: an empty string)
  • script_machine (string) – a machine name for specifying a path to a script (optional, default: an empty string)
  • script_path (string) – an absolute path to a script; see Sending Mail to a Script for details (optional, default: an empty string)

Change the details of an existing email address. The email address must exist before calling the method. The method returns a struct with the following key-value pairs:

id
email ID
email_address
email address
targets
mailboxes or email addresses to which the address is set to deliver

See also

create_email

Websites and Domains

create_domain
Parameters:
  • session_id – session ID returned by login
  • domain (string) – a domain name in the form of example.com
  • subdomain (string) – each additional parameter provided after domain: a subdomain name of domain

Create a domain entry. If domain has already been created, you may supply additional parameters to add subdomains. For example, if example.com already exists, create_domain may be called with four parameters— a session ID, example.com, www, private—to create www.example.com and private.example.com.

Example: Create a domain entry for widgetcompany.example using Python:

>>> import xmlrpclib
>>> server = xmlrpclib.ServerProxy('https://api.webfaction.com/')
>>> session_id, account = server.login('widgetsco', 'widgetsrock')
>>> server.create_domain(session_id, 'widgetcompany.example', 'www', 'design')
{'domain': 'widgetcompany.example',
 'id': 47255,
 'subdomains': ['www', 'design']}
create_website
Parameters:
  • session_id – session ID returned by login
  • website_name (string) – the name of the new website entry
  • ip (string) – IP address of the server where the entry resides
  • https (boolean) – whether the website entry should use a secure connection
  • subdomains (array) – an array of strings of (sub)domains to be associated with the website entry
  • site_apps (array) – each additional parameter provided after subdomains: an array containing a valid application name (a string) and a URL path (a string)

Create a new website entry. Applications may be added to the website entry with additional parameters supplied after subdomains. The additional parameters must be arrays containing two elements: a valid application name and a path (for example, 'htdocs' and '/').

Example: Create a website entry for widgetcompany.example‘s new Django project over HTTPS using Python:

>>> import xmlrpclib
>>> server = xmlrpclib.ServerProxy('https://api.webfaction.com/')
>>> session_id, account = server.login('widgetsco', 'widgetsrock')
>>> server.create_website(session_id,
... 'widgets_on_the_web',
... '174.133.82.194',
... True,
... ['widgetcompany.example', 'www.widgetcompany.example'],
... ['django', '/'])
{'https': True,
 'id': 67074,
 'ip': '174.133.82.194',
 'name': 'widgets_on_the_web',
 'site_apps': [['django', '/']],
 'subdomains': ['widgetcompany.example', 'www.widgetcompany.example']}
delete_domain
Parameters:
  • session_id – session ID returned by login
  • domain (string) – name of the domain to be deleted or the parent domain of the subdomains to be deleted
  • subdomains (string) – each additional parameter provided after domain: subdomains of domain to be deleted

Delete a domain record or subdomain records. Subdomains of a domain may be deleted by supplying additional parameters after domain. If any subdomains are provided, only subdomains are deleted and the parent domain remains.

delete_website
Parameters:
  • session_id – session ID returned by login
  • website_name (string) – name of website to be deleted
  • ip (string) – IP address of the server where the website resides
  • https (boolean) – whether the website uses a secure connection (optional, default: false)

Delete a website entry.

list_bandwidth_usage
Parameters:session_id – session ID returned by login

List bandwidth usage statistics for your websites (similar to usage statistics shown on the control panel). The method returns a struct containing two members:

daily: A struct containing members named for the dates for the past two weeks (for example, 2014-02-15, 2014-02-14, 2014-02-13 and so on). The value of each dated member is a struct containing members named for each domain associated with the account (for example, example.com, www.example.com, somedomain.example, www.somedomain.example and so on). The value of each domain name member is the bandwidth usage for that domain during that day in kilobytes.

monthly: A struct containing members named for the months for the past year (for example, 2014-02, 2014-01, 2013-12 and so on). The value of each month member is a struct containing members named for each domain associated with the account (for example, example.com, www.example.com, somedomain.example, www.somedomain.example and so on). The value of each domain name member is the bandwidth usage for that domain during that month in kilobytes.

Overall, the struct resembles this outline:

  • daily
    • today
      • www.example.com: 1024
      • example.com: 512
    • yesterday
    • two weeks ago
  • monthly
    • this month
      • www.example.com: 2048
      • example.com: 1024
    • last month
    • a year ago
list_domains
Parameters:session_id – session ID returned by login

Get information about the account’s domains. The method returns an array of structs with the following key-value pairs:

id
domain ID
domain
domain (for example, example.com)
subdomains
array of subdomains for the domain
list_websites
Parameters:session_id – session ID returned by login

Get information about the account’s websites. The method returns an array of structs with the following key-value pairs:

id
website ID
name
website name
ip
website IP address
https
whether the website is served over HTTPS
subdomains
array of website’s subdomains
website_apps
array of the website’s apps and their URL paths; each item in the array is a two-item array, containing an application name and URL path
update_website
Parameters:
  • session_id – session ID returned by login
  • website_name (string) – the name of the new website entry
  • ip (string) – IP address of the server where the entry resides
  • https (boolean) – whether the website entry should use a secure connection
  • subdomains (array) – an array of strings of (sub)domains to be associated with the website entry
  • site_apps (array) – each additional parameter provided after subdomains: an array containing a valid application name (a string) and a URL path (a string)

Update a website entry. Applications may be added to the website entry with additional parameters supplied after subdomains. The additional parameters must be arrays containing two elements: a valid application name and a path (for example, 'htdocs' and '/').

Example: Update a website entry for widgetcompany.example‘s new Django project over HTTPS using Python:

>>> import xmlrpclib
>>> server = xmlrpclib.ServerProxy('https://api.webfaction.com/')
>>> session_id, account = server.login('widgetsco', 'widgetsrock')
>>> server.update_website(session_id,
... 'widgets_on_the_web',
... '174.133.82.195',
... True,
... ['widgetcompany.example', 'dev.widgetcompany.example'],
... ('django', '/'), ('wordpress', '/blog'))
{'https': True,
 'id': 67074,
 'ip': '174.133.82.195',
 'name': 'widgets_on_the_web',
 'site_apps': [['django', '/'], ['wordpress', '/blog']],
 'subdomains': ['widgetcompany.example', 'dev.widgetcompany.example']}

Applications

create_app
Parameters:
  • session_id – session ID returned by login
  • name (string) – name of the application
  • type (string) – type of the application
  • autostart (boolean) – whether the app should restart with an autostart.cgi script (optional, default: false)
  • extra_info (string) – additional information required by the application; if extra_info is not required or used by the application, it is ignored (optional, default: an empty string)
  • open_port (boolean) – for applications that listen on a port, whether the port should be open on shared and dedicated IP addresses (optional, default: false)

Create a new application.

See also

For a complete list of application types, see Application Types.

delete_app
Parameters:
  • session_id – session ID returned by login
  • name (string) – name of the application

Delete an application.

list_apps
Parameters:session_id – session ID returned by login

Get information about the account’s applications. The method returns an array of structs with the following key-value pairs:

id
app ID
name
app name
type
app type
autostart
whether the app uses autostart
port
port number if the app listens on a port, otherwise is 0
open_port
for applications that listen on a port, whether the port is open on shared and dedicated IP addresses (True for open ports, False for closed ports, or for applications that do not listen to a port)
extra_info
extra info for the app if any
machine
name of the machine where the app resides
list_app_types
Parameters:session_id – session ID returned by login

Get information about available app types. The method returns an array of structs with the following key-value pairs:

description
description of the application type
name
short identifier for the application type
autostart
applicable or an empty string, indicating whether the application uses an autostart.cgi file
extra_info
description of any additional information required by the application installer’s extra_info field

See also

create_app

Cron

create_cronjob
Parameters:
  • session_id – session ID returned by login
  • line (string) – crontab line to be added

Create a new cron job.

See also

For more information about the cron syntax, please see the Wikipedia entry on cron.

delete_cronjob
Parameters:
  • session_id – session ID returned by login
  • line (string) – crontab line to be removed

Remove an existing cron job.

DNS

create_dns_override
Parameters:
  • session_id – session ID returned by login
  • domain (string) – domain name to be overridden (for example, sub.example.com)
  • a_ip (string) – A IP address (optional, default: an empty string)
  • cname (string) – CNAME record (optional, default: an empty string)
  • mx_name (string) – Mail exchanger record host name (optional, default: an empty string)
  • mx_priority (string) – Mail exchanger record priority (optional, default: an empty string)
  • spf_record (string) – TXT record (optional, default: an empty string)
  • aaaa_ip (string) – An IPv6 address (optional, default: an empty string)

Create DNS records and return an array of the new records (as in the form of list_dns_overrides).

delete_dns_override
Parameters:
  • session_id – session ID returned by login
  • domain (string) – domain name to be overridden (for example, sub.example.com)
  • a_ip (string) – A IP address (optional, default: an empty string)
  • cname (string) – CNAME record (optional, default: an empty string)
  • mx_name (string) – Mail exchanger record host name (optional, default: an empty string)
  • mx_priority (string) – Mail exchanger record priority (optional, default: an empty string)
  • spf_record (string) – TXT record (optional, default: an empty string)
  • aaaa_ip (string) – An IPv6 address (optional, default: an empty string)

Delete DNS records and return an array of the deleted records (as in the form of list_dns_overrides).

list_dns_overrides
Parameters:session_id – session ID returned by login

Get information about the account’s DNS overrides. The method returns an array of structs with the following key-value pairs:

id
domain ID
domain
domain name to be overridden (for example, sub.example.com)
a_ip
A IP address
aaaa_ip
AAAA IP address (for IPv6)
cname
CNAME record
mx_name
Mail exchanger record host name
mx_priority
Mail exchanger record priority
spf_record
TXT record
srv_record
Service record

Databases

change_db_user_password
Parameters:
  • session_id – session ID returned by login
  • username (string) – a database user’s username
  • password (string) – the new password
  • db_type (string) – the database type, either mysql or postgresql

Change a database user’s password. The method returns a struct containing the following key-value pairs:

username
database username
machine
database machine name
db_type
database type (MySQL or PostgreSQL)
database
database name

See also

See Strengthening Passwords for important information about choosing passwords.

create_db
Parameters:
  • session_id – session ID returned by login
  • name (string) – database name
  • db_type (string) – the database type, either mysql or postgresql
  • password (string) – password for the default database user

Create a database.

Note

MySQL database names may not exceed 16 characters.

See also

See Strengthening Passwords for important information about choosing passwords.

create_db_user
Parameters:
  • session_id – session ID returned by login
  • username (string) – the new database user’s username
  • password (string) – the new database user’s password
  • db_type (string) – the database type, either mysql or postgresql

Create a database user. The method returns a struct with the following key-value pairs:

machine
machine name
username
database username
db_type
database type (MySQL or PostgreSQL)

See also

See Strengthening Passwords for important information about choosing passwords.

delete_db
Parameters:
  • session_id – session ID returned by login
  • name (string) – database name
  • db_type (string) – the database type, either mysql or postgresql

Delete a database.

delete_db_user
Parameters:
  • session_id – session ID returned by login
  • username (string) – the database user’s username
  • db_type (strings mysql or postgresql) – the database type

Delete a database user. The method returns a struct with the following key-value pairs:

machine
machine name
username
database username
db_type
database type (MySQL or PostgreSQL)
enable_addon
Parameters:
  • session_id – session ID returned by login
  • database (string) – a database name
  • db_type (string) – the database type (always use postgresql)
  • addon (string) – the addon to enable (tsearch or postgis)

Enable a database addon. The method returns a struct with the following key-value pairs:

machine
machine name
db_type
database type (always PostgreSQL)
addon
addon enabled
db_type
database type (MySQL or PostgreSQL)

Note

This method applies to PostgreSQL databases only.

grant_db_permissions
Parameters:
  • session_id – session ID returned by login
  • username (string) – a database user’s username
  • database (string) – a database name
  • db_type (string) – the database type (mysql or postgresql)

Grant full database permissions to a user with respect to a database. The method returns a struct with the following key-value pairs:

machine
machine name
username
database username
db_type
database type (MySQL or PostgreSQL)
database
database name
list_dbs
Parameters:session_id – session ID returned by login

Get information about the account’s databases. The method returns an array of structs with the following key-value pairs:

id
database ID
name
database name
db_type
database type (MySQL or PostgreSQL)
machine
machine name
list_db_users
Parameters:session_id – session ID returned by login

Get information about the account’s database users. The method returns an array of structs with the following key-value pairs:

machine
machine name
username
database username
db_type
database type (MySQL or PostgreSQL)
make_user_owner_of_db
Parameters:
  • session_id – session ID returned by login
  • username (string) – a database user’s username
  • database (string) – a database name
  • db_type (string) – the database type (mysql or postgresql)

Assign ownership of a database to a user. The method returns a struct with the following key-value pairs:

machine
machine name
username
database username
db_type
database type (MySQL or PostgreSQL)
database
database name
revoke_db_permissions
Parameters:
  • session_id – session ID returned by login
  • username (string) – a database user’s username
  • database (string) – a database name
  • db_type (string) – the database type (mysql or postgresql)

Revoke a user’s permissions with respect to a database. The method returns a struct with the following key-value pairs:

machine
machine name
username
database username
db_type
database type (MySQL or PostgreSQL)
database
database name

Files

replace_in_file
Parameters:
  • session_id – session ID returned by login
  • filename (string) – path to file from the user’s home directory
  • changes (array) – each additional parameter provided after filename: an array of two strings, where the first is the text to be replaced and the second is the replacement text

Find and replace strings in a file in the users’s home directory tree.

Any parameters after filename must be arrays containing a pair of strings, where the first is the string to be replaced and the second is the replacement text.

Example: Find all appearances of the word “eggs” in a file in the user’s home directory and replace them with the word “spam” using Python:

$ cat myfile.txt
eggs, spam, spam, and spam.
spam, spam, spam, and eggs.
>>> import xmlrpclib
>>> server = xmlrpclib.ServerProxy('https://api.webfaction.com/')
>>> session_id, account = server.login('widgetsco', 'widgetsrock')
>>> server.replace_in_file(session_id, 'myfile.txt', ('eggs', 'spam'))
''
>>> exit()
$ cat myfile.txt
spam, spam, spam, and spam.
spam, spam, spam, and spam.

replace_in_file

write_file
Parameters:
  • session_id – session ID returned by login
  • filename (string) – path to file to be written from the user’s home directory
  • str (string) – string to be written
  • mode (string) – write mode (optional, default: wb)

Write a string to a file in the user’s home directory tree.

Note

Commonly, the write mode is w for plain text and wb for binaries. a and ab can be used to append to files.

See also

For more information about write modes, please see open().

Shell Users

change_user_password
Parameters:
  • session_id – session ID returned by login
  • username (string) – username
  • password (string) – a new passowrd

Change a shell user’s password.

See also

See Strengthening Passwords for important information about choosing passwords.

create_user
Parameters:
  • session_id – session ID returned by login
  • username (string) – username
  • shell (string) – the user’s command line interpreter; one of none, bash, sh, ksh, csh, or tcsh.
  • groups (array) – extra permission groups of which the new user is to be a member

Create a new shell user. If shell is none, the user has FTP access only. All users are automatically a member of their own group; do not include the user’s own group in groups. Use an empty array to specify no extra groups.

delete_user
Parameters:
  • session_id – session ID returned by login
  • username (string) – username

Delete a user.

list_users
Parameters:session_id – session ID returned by login

Get information about the account’s shell users. The method returns an array of structs with the following key-value pairs:

username
username
machine
the user’s server (for example, Web100)
shell
the user’s configured command line interpreter (for example, bash or tcsh)
groups
extra permissions groups of which the user is a member

Servers

list_ips
Parameters:session_id – session ID returned by login

Get information about all of the account’s machines and their IP addresses. This method returns an array of structs with the following key-value pairs:

machine
machine name (for example, Web100)
ip
IP address
is_main
a boolean value indicating whether the IP address is the primary address for the server (true) or an extra IP address provisioned to the account (false)
list_machines
Parameters:session_id – session ID returned by login

Get information about the account’s machines. This method returns an array of structs with the following key-value pairs:

name
machine name (for example, Web100)
operating_system
the machine’s operating system (for example, Centos6-64bit)
location
the machine’s location (for example, USA)

Miscellaneous

run_php_script
Parameters:
  • session_id – session ID returned by login
  • script (string) – an absolute path to script (or path to the script starting from the user’s home directory)
  • code_before (string) – PHP code to be executed before script

Run PHP code followed by a PHP script. The PHP code and script is run as the user.

set_apache_acl
Parameters:
  • session_id – session ID returned by login
  • paths (string or array of strings) – path from home directory
  • permission (string) – r, w, or x or a combination thereof (optional, default: rwx)
  • recursive (boolean) – whether Apache’s access is granted recursively (optional, default: false)

Grant the machine-wide Apache instance access to files or directories.

system
Parameters:
  • session_id – session ID returned by login
  • cmd (string) – a shell command to be executed

Execute a command as the user, as if through SSH. If an application was installed previously in the session, the command will be run from the directory where that application was installed.

Note

If cmd writes to standard error, the API method will return an XML-RPC fault.

Previous topic

Tutorial

Next topic

Application Types

Search the documentation

Example: "configure email" or "create database"

Feedback

Send us your feedback on this documentation.