Tutorial

This tutorial provides a step-by-step walkthrough of WP Engine’s Hosting Platform API. You’ll learn how to authenticate, query resources, handle pagination, and respond to errors.

Steps

1. Authenticate

The API uses Basic Auth with your User ID and Password from the API Access page of the WP Engine User Portal.

Store your credentials in environment variables:

export WPE_API_USER_ID="YOUR_API_USER_ID"
export WPE_API_PASSWORD="YOUR_API_PASSWORD"

Then construct the Authorization header:

curl -u $WPE_API_USER_ID:$WPE_API_PASSWORD \
  https://api.wpengineapi.com/v1/installs?limit=3

2. List Installs

The /installs endpoint returns all WordPress installs accessible to your account.

Example request:

curl -X GET "https://api.wpengineapi.com/v1/installs?limit=3" \
  -u $WPE_API_USER_ID:$WPE_API_PASSWORD

Example response:

{
  "count": 232,
  "results": [
    {
      "id": 12345,
      "name": "marketing-site",
      "account_id": 67890,
      "created_at": "2024-01-01T12:00:00Z"
    },
    {
      "id": 12346,
      "name": "blog-site",
      "account_id": 67890,
      "created_at": "2024-01-02T15:00:00Z"
    }
  ],
  "next": "https://api.wpengineapi.com/v1/installs?limit=3&offset=3"
}

3. Handle Pagination

Many list endpoints return large result sets. The API uses offset-based pagination.

limit: number of results per page (max 100).
offset: number of results to skip.

Example:

curl "https://api.wpengineapi.com/v1/installs?limit=5&offset=5" \
  -u $WPE_API_USER_ID:$WPE_API_PASSWORD

The response will include next and previous URLs for easy navigation:

{
  "previous": "https://api.wpengineapi.com/v1/installs?limit=5&offset=0",
  "next": "https://api.wpengineapi.com/v1/installs?limit=5&offset=10",
  "count": 232,
  "results": [...]
}

When no previous or next page exists, the value of next/previous will be null.

4. Fetch a Single Resource

You can fetch a single install by ID:

curl "https://api.wpengineapi.com/v1/installs/12345" \
 -u $WPE_API_USER_ID:$WPE_API_PASSWORD

Response:

{
  "id": 12345,
  "name": "marketing-site",
  "account_id": 67890,
  "created_at": "2024-01-01T12:00:00Z",
  "domains": [{ "hostname": "marketing.example.com", "primary": true }]
}

5. Handle Errors

The API uses standard HTTP status codes.

2xx — success.
4xx — validation or request error.
5xx — server error.

Example of a 400 Bad Request:

curl "https://api.wpengineapi.com/v1/installs?limit=5000" \
  -u $WPE_API_USER_ID:$WPE_API_PASSWORD

Response:

{
  "type": "invalid_value",
  "code": "too_large",
  "message": "Limit cannot exceed 100."
}

Always check the response body for structured error details.

6. Automate Workflows

With the basics in place, you can script automation:

Sync site data into dashboards.
Trigger cache purges or deploys from CI/CD pipelines.
Run scheduled tasks against installs or domains.

Example JavaScript snippet to loop through all installs with pagination:

async function getAllInstalls() {
  let url = "https://api.wpengineapi.com/v1/installs?limit=100";
  const user = process.env.WPE_API_USER_ID;
  const pass = process.env.WPE_API_PASSWORD;
  const auth = "Basic " + Buffer.from(`${user}:${pass}`).toString("base64");

  while (url) {
    const res = await fetch(url, { headers: { Authorization: auth } });
    const data = await res.json();

    data.results.forEach((install) => {
      console.log(install.name);
    });

    url = data.next; // continue if more pages
  }
}

getAllInstalls();

Next Steps

Now that you’ve seen authentication, pagination, and error handling, you can:

Explore more endpoints in the API Reference.