WPEngine – API – Start Off

/ INTERNAL, SprUng, wordpress - more cheats / 6 minutes of reading

Getting Started

The easiest way to get started with the WP Engine API is to use the “Try it out” buttons found in the API Reference documentation. Use the “Authorize” button to input your Basic Auth credentials for authenticated API requests. Eligible users can generate their own credentials in the WP Engine User Portal.

Authentication

Authentication is done with Basic Auth. See this example curl command:

[code style="php"]curl -X GET <span style="color: rgb(152, 195, 121);">"https://api.wpengineapi.com/v1/sites"</span> -u PUT_USER_ID_HERE:PUT_PASSWORD_HERE[/code]

Best Practices

Basic Auth credentials give a script or a person the ability to act on your behalf, so treat your credentials with the same care as other passwords. If your Basic Auth credentials become compromised, delete them in the WP Engine User Portal and generate a new set.

Pagination

The WP Engine “list” operations can match a large amount of data in certain scenarios. The API uses offset-based pagination to page through all of the matching results using two query string parameters:

  • [code style=”php”]limit[/code]: the maximum number of results that you would like per page
  • [code style=”php”]offset[/code]: the number of results to skip for the start of the page

For example, the following URL will yield 10 results starting with the 40th install: [code style=”php”]GET http://api.wpengineapi.com/v1/installs?limit=10&offset=40[/code]

The payload includes three fields: [code style=”php”]count[/code]provides the total number of matched results. By default, a maximum of 100 results are returned per page. When there are more results to page, [code style=”php”]next[/code]contains a fully formed URL to fetch the next page. While paging, the [code style=”php”]previous[/code]field contains a fully formed URL for the previous page.

[code style="php"]{
  <span style="color: rgb(152, 195, 121);">previous</span>: <span style="color: rgb(152, 195, 121);">"http://api.wpengineapi.com/v1/installs?limit=100&offset=100"</span>,
  next: <span style="color: rgb(152, 195, 121);">"http://api.wpengineapi.com/v1/installs?limit=100&offset=200"</span>,
  count: <span style="color: rgb(209, 154, 102);">232</span>,
  results: [
    ...
  ]
}[/code]

Responses and Errors

WP Engine API uses Standard HTTP Response Codes to indicate
the success or failure of your request. The 3 main categories of error codes are:

  • [code style=”php”]2xx[/code]: Success status codes representing the successful processing of your request. Depending on the type of the request,
    you can expect a JSON response body.
  • [code style=”php”]4xx[/code]: Error status codes indicating a validation or data error because of the input provided. A JSON response including
    detailed field-level errors is returned.
  • [code style=”php”]5xx[/code]: Errors indicating something unexpected happened in the WP Engine servers.

Some [code style=”php”]4xx[/code]errors return detailed field-level errors with [code style=”php”]type[/code], [code style=”php”]code[/code]and [code style=”php”]message[/code]attached to a [code style=”php”]resource[/code]and [code style=”php”]field[/code]that can be handled programatically.
The [code style=”php”]type[/code]of the error provides a general classification of the error. The values below are currently supported:

Error Type Description
[code style=”php”]invalid_value[/code] Indicates that the value provided failed validation. The [code style=”php”]code[/code]generally provides more detail about the type of failed validation. Example [code style=”php”]code[/code]values for this error type are [code style=”php”]too_long[/code], [code style=”php”]blank[/code].
[code style=”php”]value_unavailable[/code] Indicates that the value provided is generally valid but is unavailable (e.g., Site name already taken). Example [code style=”php”]code[/code]value for this error type is [code style=”php”]taken[/code].
[code style=”php”]access_error[/code] Indicates a general error related to access or setup of the resource. Example [code style=”php”]code[/code]values for this [code style=”php”]type[/code]are [code style=”php”]at_or_over_site_limit[/code], [code style=”php”]group_account_mismatch[/code].

Payload

The API is user-oriented, so the payload for the [code style=”php”]GET https://api.wpengineapi.com/v1/installs[/code]request will include all of the installs that the current user can access.

Note that an account must be explicitly enabled in order for the account’s installs, sites, and domains to work with the API. All users can see the status of their accounts via the API Access page in the WP Engine User Portal, but only account owners have the ability to enable/disable API access.

Code Samples

Store your API credentials in the [code style=”php”]WPENGINE_USER_ID[/code]and [code style=”php”]WPENGINE_PASSWORD[/code]environment variable before running the code samples. On Mac and Linux, you can use export to set the environment variable:

[code style="php"]<span style="color: rgb(230, 192, 123);">export</span> WPENGINE_USER_ID=<span style="color: rgb(152, 195, 121);">"PUT_USER_ID_HERE"</span>
<span style="color: rgb(230, 192, 123);">export</span> WPENGINE_PASSWORD=<span style="color: rgb(152, 195, 121);">"PUT_PASSWORD_HERE"</span>[/code]

Node

This sample will query the installs endpoint and return a list of installs:

[code style="php"]<span style="color: rgb(198, 120, 221);">const</span> fetch = <span style="color: rgb(230, 192, 123);">require</span>(<span style="color: rgb(152, 195, 121);">'node-fetch'</span>);
<span style="color: rgb(198, 120, 221);">const</span> WPENGINE_PASSWORD = process.env.WPENGINE_PASSWORD;
<span style="color: rgb(198, 120, 221);">const</span> WPENGINE_USER_ID = process.env.WPENGINE_USER_ID;

<span style="color: rgb(198, 120, 221);">const</span> authorization = <span style="color: rgb(152, 195, 121);">"Basic "</span> + Buffer.from(WPENGINE_USER_ID + <span style="color: rgb(152, 195, 121);">":"</span> + WPENGINE_PASSWORD).toString(<span style="color: rgb(152, 195, 121);">'base64'</span>)

fetch(<span style="color: rgb(152, 195, 121);">'https://api.wpengineapi.com/v1/installs?limit=10'</span>, {
    <span style="color: rgb(209, 154, 102);">method</span>: <span style="color: rgb(152, 195, 121);">'GET'</span>,
    <span style="color: rgb(209, 154, 102);">headers</span>: { <span style="color: rgb(152, 195, 121);">'Authorization'</span>: authorization },
})
  .then(<span><span>res</span> =></span> res.json())
  .then(<span><span>json</span> =></span> <span style="color: rgb(230, 192, 123);">console</span>.log(json));[/code]

Ruby

Requires faraday, faraday_middleware, and pp gems

[code style="php"]<span style="color: rgb(198, 120, 221);">require</span> <span style="color: rgb(152, 195, 121);">'faraday'</span>
<span style="color: rgb(198, 120, 221);">require</span> <span style="color: rgb(152, 195, 121);">'faraday_middleware'</span>
<span style="color: rgb(198, 120, 221);">require</span> <span style="color: rgb(152, 195, 121);">'pp'</span>
WPENGINE_USER_ID = ENV[<span style="color: rgb(152, 195, 121);">'WPENGINE_USER_ID'</span>]
WPENGINE_PASSWORD = ENV[<span style="color: rgb(152, 195, 121);">'WPENGINE_PASSWORD'</span>]

connection = Faraday.new(<span style="color: rgb(152, 195, 121);">'https://api.wpengineapi.com/'</span>) <span style="color: rgb(198, 120, 221);">do</span> <span>|conn|</span>
  conn.response <span style="color: rgb(97, 174, 238);">:json</span>, <span style="color: rgb(97, 174, 238);">content_type:</span> /bjson$/
  conn.basic_auth(WPENGINE_USER_ID, WPENGINE_PASSWORD)
  conn.adapter Faraday.default_adapter
<span style="color: rgb(198, 120, 221);">end</span>
response = connection.get(<span style="color: rgb(152, 195, 121);">'/v1/installs?limit=10'</span>)
pp response.body
exit response.success?[/code]

Python

[code style="php"]<span style="color: rgb(198, 120, 221);">import</span> requests
<span style="color: rgb(198, 120, 221);">import</span> os
url = <span style="color: rgb(152, 195, 121);">"https://api.wpengineapi.com/v1/installs?limit=10"</span>

response = requests.get(url,
    auth=requests.auth.HTTPBasicAuth(
    os.environ[<span style="color: rgb(152, 195, 121);">'WPENGINE_USER_ID'</span>],
    os.environ[<span style="color: rgb(152, 195, 121);">'WPENGINE_PASSWORD'</span>]))

print(response.text)[/code]

PHP

[code style="php"]<span style="color: rgb(97, 174, 238);"><?php</span>
$ch = curl_init();

curl_setopt( $ch, CURLOPT_URL, <span style="color: rgb(152, 195, 121);">'https://api.wpengineapi.com/v1/installs'</span> );
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, <span style="color: rgb(209, 154, 102);">1</span> );
curl_setopt( $ch, CURLOPT_CUSTOMREQUEST, <span style="color: rgb(152, 195, 121);">'GET'</span> );

$headers = <span style="color: rgb(198, 120, 221);">array</span>();
$cred_string = $_ENV[<span style="color: rgb(152, 195, 121);">'WPENGINE_USER_ID'</span>] . <span style="color: rgb(152, 195, 121);">":"</span> . $_ENV[<span style="color: rgb(152, 195, 121);">'WPENGINE_PASSWORD'</span>];
$headers[] = <span style="color: rgb(152, 195, 121);">"Authorization: Basic "</span> . base64_encode($cred_string);
curl_setopt( $ch, CURLOPT_HTTPHEADER, $headers );

$result = curl_exec( $ch );
<span style="color: rgb(198, 120, 221);">if</span> ( curl_errno( $ch ) ) {
    <span style="color: rgb(198, 120, 221);">echo</span> <span style="color: rgb(152, 195, 121);">'Error:'</span> . curl_error( $ch );
}

<span style="color: rgb(198, 120, 221);">echo</span> $result;
curl_close( $ch );[/code]

Bugs / Limitations / Warnings

Account Data Access

You will only be able to access data for accounts that are API-enabled.
If you do not see the data you are expecting, please ask your account owner to enable the API for the account.

Sites

  • The Sites feature is not yet available to all customers and may not apply to your account at this time.
  • Create site operation only takes the name property, with no additional options.
    • For example, you currently cannot create a multisite install or associate a site with a group.

Installs

  • Please be mindful when creating installs in large batches, as doing so can potentially:
    • Degrade the performance of the entire cluster that the installs are hosted on.
    • Overload the cluster, causing the provisioning of the installs to fail.
  • Update install operation currently only applies to the new Sites feature in Portal, which is not yet available to all customers (as noted above).
    • For example, it currently only allows an install to be moved into a site with multiple environments.
  • Create install operation is rate limited, so multiple create installs in quick succession will return a “Too many requests” message.

Domains

  • Please be mindful when creating domains in large batches, as doing so can degrade the performance of API requests related to the corresponding install.
  • Create and update domain operations are rate limited. Multiple requests to these operations in quick succession will return a “Too many requests” message.

Caches

  • Cache purging is rate limited. The limit is unique for each type (object, page or CDN) due to the nature of the cache type. Multiple requests to purge the same cache type in quick succession will return a “Too many requests” message.
Scroll to Top