API quickstart

1. Generate an API key

From the admin console, open Settings > API Keys and click Create key. Give it a clear name (e.g. ci-deploy-bot) and an expiry (we recommend ≤ 12 months). The key is shown once; copy it somewhere safe.

API keys are prefixed ppk_ and are stored hashed (SHA-256) on the server — we cannot retrieve a lost key, only revoke and reissue.

2. Make your first call

List the devices in your organisation:

curl -fsSL https://patchpilot.co.uk/api/devices \
  -H "Authorization: Bearer ppk_your_key_here" \
  -H "Accept: application/json"

Response (truncated):

{
  "devices": [
    {
      "device_id": "dev_01HXYZ...",
      "hostname": "FINANCE-LAPTOP-04",
      "os_family": "windows",
      "os_name": "Windows 11 Pro",
      "status": "online",
      "last_seen": "2026-04-26T09:14:22Z",
      "updates_available": 7,
      "critical_count": 1
    }
  ],
  "total": 84
}

3. Common endpoints

Method	Path	Purpose
GET	/api/devices	List devices in your org
GET	/api/devices/:id	Fetch a single device's full state
GET	/api/vulnerabilities	List CVEs detected across the fleet
GET	/api/compliance/snapshot	Export the latest compliance snapshot
GET	/api/reboot-management	Devices pending a reboot
POST	/api/reboot-management/:id/schedule	Schedule a reboot
GET	/api/patch-exclusions	List KB / package blocklist entries
POST	/api/patch-exclusions	Add a blocklist entry

4. Auth scheme

• ppk_ keys — admin / integration scope, used in the Authorization: Bearer header.
• ppdt_ tokens — per-device tokens issued during enrolment. Used by the agent only; not for human integrations.

5. Rate limits

The API is rate-limited per key:

• 120 requests per minute on read endpoints.
• 30 requests per minute on write endpoints.

If you exceed a limit you'll get HTTP 429 with a Retry-After header. Back off and retry.

6. Webhooks

For event-driven integrations, configure a webhook in Integrations > Webhooks. PatchPilot will POST a JSON payload to your endpoint for events like device.online, patch.failed, compliance.drift_detected. Each delivery is signed with HMAC-SHA256 using your webhook secret — verify the X-Patchpilot-Signature header before trusting the body.