---
title: "API: getting started"
url: https://wpforeman.com/docs/api-getting-started/
description: "Create a token, call https:\/\/app.wpforeman.com\/api\/v1, and read the conventions every endpoint follows."
updated: 2026-10-11
---

# API: getting started

The WP Foreman API lets your own scripts and tools (Zapier, Make, a reporting dashboard, an AI agent) do what you do in the app: list sites, run backups, restore, clone, and install or update plugins.

## 1. Create a token

1. In the app, open **Settings › API tokens**.
2. Give the token a name and tick what it’s allowed to do (its **abilities**).
3. Click **Create token** and copy it straight away. It’s shown once.

| Ability | Allows |
| --- | --- |
| `read` | Read sites, clients, backups, restores, updates and activity |
| `sites` | Add sites and clients, refresh inventory |
| `backups` | Run backups, change backup settings, build.zip downloads |
| `restore` | Restore and clone backups (overwrites sites) |
| `plugins` | Install, activate, update and delete plugins, themes and WordPress |
| `webhooks` | Subscribe and unsubscribe [webhooks](https://wpforeman.com/docs/api-webhooks/) |
| `rules` | Create, change, delete and run [rules](https://wpforeman.com/docs/api-rules/) |

Treat tokens like passwords. Give each tool its own token with only the abilities it needs, and revoke it from **Settings › API tokens** if it leaks. Tokens start with `wpf_` so secret scanners can spot them.

## 2. Make a request

Send the token as a Bearer token. Everything is JSON.

```
curl https://app.wpforeman.com/api/v1/me \
  -H "Authorization: Bearer YOUR_TOKEN"
```

```
{
  "data": {
    "id": 1, "name": "Nate", "email": "you@example.com", "timezone": "America/New_York",
    "token": { "name": "Zapier", "abilities": ["read"] }
  }
}
```

## Conventions

- **Base URL:** `https://app.wpforeman.com/api/v1`
- **Responses** wrap results in `data`. Lists that can grow (backups, restores, activity) are paged: `?page=2&per_page=50` (max 100), with `meta.page`, `meta.last_page` and `meta.total`.
- **Long jobs** (backups, restores, clones, updates, installs) answer `202 Accepted` with the job record. Poll its URL until `status` is `succeeded`, `partial` or `failed`.
- **Dates** are ISO 8601 in UTC.
- **Rate limit:** 120 requests a minute per token. Over that you get `429`; wait and retry.

## Errors

| Status | Meaning |
| --- | --- |
| `401` | Missing or revoked token |
| `403` | The token doesn’t have the ability this needs |
| `404` | Not found, or not yours |
| `409` | Can’t right now: site busy (a backup, restore or update is running), not connected, or the plugin is too old |
| `422` | Invalid input; `errors` lists each field |
| `429` | Rate limited |

Every error has a human-readable `message`:

```
{ "message": "A backup, restore or update is already running on Shop." }
```

## Safety

The API follows the same rules as the app: a safety backup runs before every restore and clone, updates and deletes back up first unless you send `"backup_first": false`, the WP Foreman plugin is never overwritten, and `wp-config.php` is left alone unless you send `"include_wp_config": true`. The app’s type-the-domain confirmation is replaced by the `restore` ability, so only give that ability to tools you trust.

---

WP Foreman: WordPress site management for agencies and freelancers. First site free, no card: https://app.wpforeman.com/signup