---
title: Tutorial
description: A step-by-step walkthrough of WP Engine's Hosting Platform API, including authentication, pagination, and error handling.
url: https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/
image: https://developers.wpengine.com/og/docs/managed-hosting-platform/api/tutorial.png
---

# 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

### 0. Prerequisites

- The cURL pagination loop later uses `jq` for JSON parsing. Install via Homebrew: `brew install jq`.
- JavaScript examples rely on top-level `await` (Node 18+ or any modern runtime supporting ESM).
- Python examples require the `requests` library. Install with `pip install requests`.

### 1. Authenticate

The API uses **Basic Auth** with your User ID and Password from the [API Access page](https://my.wpengine.com/api_access) of the WP Engine User Portal.

Store your credentials in environment variables (we’ll use `WPE_API_USER_ID` and `WPE_API_PASSWORD` consistently across all language examples):

```ini
# Exact method for storing env vars may vary by OS/shell/developer preference/etc
WPE_API_USER_ID="YOUR_API_USER_ID"
WPE_API_PASSWORD="YOUR_API_PASSWORD"
```

Then construct the Authorization header:

- [cURL](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-0-0)
- [Go](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-0-1)
- [JavaScript](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-0-2)
- [Python](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-0-3)

Authenticate

```bash
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](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-1-0)
- [Go](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-1-1)
- [JavaScript](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-1-2)
- [Python](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-1-3)

List Installs

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

Example response:

```json
{
  "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://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-2-0)
- [Go](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-2-1)
- [JavaScript](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-2-2)
- [Python](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-2-3)

Paginated Request

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

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

```json
{
  "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://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-3-0)
- [Go](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-3-1)
- [JavaScript](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-3-2)
- [Python](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-3-3)

Get Single Install

```bash
# Placeholder ID 12345 used for illustration; replace with a real install ID.
# A 404 response means the placeholder doesn't exist in your account.
curl -u "$WPE_API_USER_ID:$WPE_API_PASSWORD" \
  "https://api.wpengineapi.com/v1/installs/12345"
```

Response:

```json
{
  "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://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-4-0)
- [Go](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-4-1)
- [JavaScript](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-4-2)
- [Python](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-4-3)

Bad Request

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

Response:

```json
{
  "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.

Below are examples that iterate through every page of installs until no further `next` link is provided.

These loops may output many lines if you have numerous installs.

- [cURL](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-5-0)
- [Go](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-5-1)
- [JavaScript](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-5-2)
- [Python](https://developers.wpengine.com/docs/managed-hosting-platform/api/tutorial/#tab-panel-5-3)

Pagination Loop

```bash
# Requires: WPE_API_USER_ID / WPE_API_PASSWORD env vars
# Iterate through all pages using the 'next' link. Requires jq.
NEXT="https://api.wpengineapi.com/v1/installs?limit=100"
AUTH="${WPE_API_USER_ID}:${WPE_API_PASSWORD}"
while [ -n "$NEXT" ] && [ "$NEXT" != "null" ]; do
  RESP=$(curl -u "$AUTH" "$NEXT")
  echo "$RESP" | jq -r '.results[]?.name'
  NEXT=$(echo "$RESP" | jq -r '.next')
done
```

## Next Steps

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

- **Explore more endpoints in the [API Reference](https://developers.wpengine.com/docs/managed-hosting-platform/api/reference/).**

## Was this helpful?

Thanks for the feedback!

```json
{"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]}
```