---
title: "Partner API for Agencies and Hosting Companies"
slug: "partner-api"
description: "Integrate WP Vanguard scanning and cleanup into your hosting platform or agency workflow with our Partner API. Rate-limited, quota-managed REST endpoints."
order: 11
---

## Overview

The WP Vanguard Partner API lets hosting companies and agencies integrate WordPress security scanning directly into their platforms. Run surface scans, deep scans, and malware cleanups programmatically - the same tools our web dashboard uses, available as a REST API.

Partners get an API key, rate limits based on their tier, monthly quotas, and optional webhook notifications when scans complete.

## Who Is This For?

- **Managed hosting providers** who want to offer security scanning to their customers
- **WordPress agencies** managing 50+ client sites who need automated scanning
- **Maintenance services** that include security checks in their monthly plans
- **Platform integrators** building WordPress management dashboards

## Getting Started

Sign up for a partner account directly from our website. The Free tier gives you immediate API access with 100 surface scans per month — no credit card required. Paid tiers unlock deep scans, cleanups, and higher quotas.

**To get started:**
1. Visit [wpvanguard.com/pricing](/pricing#partners) and pick a plan
2. Create your account — Free tier is instant, paid tiers go through Stripe Checkout
3. Your API key is generated automatically on signup
4. Authenticate requests with your `X-Api-Key` header and start scanning

For Enterprise volume (50,000+ scans/month), [create an Enterprise account](/partner/register?tier=enterprise) and we'll reach out within 24 hours to set up a custom plan.

## Authentication

Every API request (except the health check) requires your API key in the `X-Api-Key` header:

```bash
curl -H "X-Api-Key: your_api_key_here" \
  https://wpvanguard.com/api/v1/account
```

Invalid or expired keys return `401 Unauthorized`. Disabled accounts return `403 Forbidden`.

## API Base URL

```
https://wpvanguard.com/api/v1
```

## Core Endpoints

### Surface Scan

Scan any WordPress site over HTTP. No SSH access needed. Returns version info, security headers, SSL status, blacklist status, exposed files, and a security grade.

```bash
curl -X POST https://wpvanguard.com/api/v1/scans/surface \
  -H "X-Api-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
```

**Response (201):**
```json
{
  "scan_id": 42,
  "status": "queued",
  "url": "https://example.com",
  "poll_url": "/api/v1/scans/42/status"
}
```

### Deep Scan

Requires SSH access to the site. Checks WordPress core file integrity, plugin/theme authenticity, malware signatures, database injections, and suspicious admin accounts.

```bash
curl -X POST https://wpvanguard.com/api/v1/scans/deep \
  -H "X-Api-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": 5,
    "scan_type": "deep"
  }'
```

You must first register the site with SSH credentials using the `/sites` endpoint.

### Bulk Scan

Submit up to 100 surface scans in one request:

```bash
curl -X POST https://wpvanguard.com/api/v1/scans/bulk \
  -H "X-Api-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"sites": [{"url": "https://site1.com"}, {"url": "https://site2.com"}]}'
```

### Poll Scan Status

Check scan progress without waiting:

```bash
curl https://wpvanguard.com/api/v1/scans/42/status \
  -H "X-Api-Key: your_key"
```

**Response:**
```json
{
  "scan_id": 42,
  "status": "completed",
  "progress": 100,
  "grade": "B",
  "issues_found": 3
}
```

### Get Full Scan Results

```bash
curl https://wpvanguard.com/api/v1/scans/42 \
  -H "X-Api-Key: your_key"
```

Returns the complete scan report including all detected issues, severity levels, and recommendations.

### Register a Site (for Deep Scans)

```bash
curl -X POST https://wpvanguard.com/api/v1/sites \
  -H "X-Api-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://client-site.com",
    "ssh": {
      "host": "server.example.com",
      "port": 22,
      "username": "wp_user",
      "key": "-----BEGIN OPENSSH PRIVATE KEY-----...",
      "wp_path": "/var/www/html"
    }
  }'
```

SSH credentials are encrypted at rest. You can provide either `ssh.key` or `ssh.password`.

### Request a Cleanup

```bash
curl -X POST https://wpvanguard.com/api/v1/cleanups \
  -H "X-Api-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"site_id": 5}'
```

## Rate Limits and Quotas

Every response includes rate limit headers:

```
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1709301600
X-Quota-Limit: 2000
X-Quota-Remaining: 1847
X-Quota-Reset: 2026-03-31T23:59:59+00:00
```

Rate limits are per-minute and per-scan-type. Monthly quotas reset on the 1st of each month.

If you hit a rate limit, you receive `429 Too Many Requests`. If you exhaust your monthly quota, you receive `403 Forbidden` with a quota exceeded message.

### Tiers

| Tier | Price | Surface/min | Deep/min | Monthly Surface | Monthly Deep | Monthly Cleanup |
|------|-------|-------------|----------|-----------------|--------------|-----------------|
| Free | $0 | 3 | — | 100 | — | — |
| Starter | $99/mo | 5 | 1 | 500 | 50 | 5 |
| Growth | $299/mo | 10 | 2 | 2,000 | 200 | 20 |
| Scale | $799/mo | 20 | 5 | 10,000 | 1,000 | 100 |
| Enterprise | Custom | 50 | 10 | 50,000 | 5,000 | 500 |

## Webhooks

Instead of polling for scan status, configure a webhook URL to receive notifications when scans complete:

```bash
curl -X POST https://wpvanguard.com/api/v1/webhooks \
  -H "X-Api-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://your-platform.com/hooks/wpvanguard"}'
```

When a scan completes, we POST to your URL:

```json
{
  "event": "scan.completed",
  "scan_id": 42,
  "url": "https://example.com",
  "status": "completed",
  "grade": "B",
  "issues_found": 3
}
```

Webhook requests include an `X-Signature` header with an HMAC-SHA256 signature you can verify using your API secret. Failed deliveries are retried 3 times with exponential backoff.

## Idempotency

For safe retries, include an `Idempotency-Key` header on POST requests:

```bash
curl -X POST https://wpvanguard.com/api/v1/scans/surface \
  -H "X-Api-Key: your_key" \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
```

If the same idempotency key is sent within 24 hours, you receive the cached response with `X-Idempotent-Replayed: true` - no duplicate scan is created.

## IP Whitelisting

Lock your API key to specific IP addresses for additional security:

```bash
curl -X PUT https://wpvanguard.com/api/v1/account/allowed-ips \
  -H "X-Api-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"ips": ["203.0.113.0/24", "198.51.100.5"]}'
```

CIDR notation is supported. Requests from IPs not in the whitelist receive `403 Forbidden`.

## Error Handling

All errors return a consistent JSON format:

```json
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please try again in 45 seconds."
  }
}
```

| HTTP Status | Error Code | Meaning |
|-------------|-----------|---------|
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 403 | FORBIDDEN | Key expired, account disabled, or IP blocked |
| 403 | QUOTA_EXCEEDED | Monthly quota exhausted |
| 404 | NOT_FOUND | Resource not found |
| 422 | VALIDATION_FAILED | Invalid request data |
| 429 | RATE_LIMITED | Per-minute rate limit hit |

## Partner Portal

Partners also get access to a web portal at `wpvanguard.com/partner/login` where you can:

- View your usage dashboard
- Browse your sites and scan results
- Check API logs
- See your API key details

## OpenAPI Specification

A complete OpenAPI 3.0 specification is available for generating client SDKs and exploring the API in tools like Swagger UI or Postman. Contact us for access.

## Check Your Usage

```bash
curl https://wpvanguard.com/api/v1/usage \
  -H "X-Api-Key: your_key"
```

Returns your current month's usage against your tier limits.

## Manage Your Subscription

Paid tier partners can upgrade, downgrade, or cancel their subscription from the Partner Portal under **Subscription**. Free tier partners can upgrade to a paid plan at any time — no data is lost.

## Questions?

Reach out to [partner@wpvanguard.com](mailto:partner@wpvanguard.com) for tier upgrades, enterprise plans, or technical support.