API Quick Start

Get your first API call working in under two minutes.

1. Create an API key

Go to Settings → API Keys and press Create Key. Choose the scopes you need. Start with servers:read and alerts:read — you can add more later.

Key format: wk_live_ followed by 56 hex characters

Store it in an environment variable, never in source code.

2. Make your first request

Pass the key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://vigilhold.com/api/v1/servers

All responses are application/json. Errors follow the shape { "error": "message" }.

3. Base URL and versioning

All API endpoints live under:

https://vigilhold.com/api/v1

The v1 prefix is stable. Breaking changes will be introduced under v2.

4. Rate limits

Requests under /api/v1 are rate-limited per key, with a separate, lower allowance for writes (events, key rotation and webhook changes).

Over the limit you receive HTTP 429 with a Retry-After header in seconds. Wait that long and retry.

5. Pagination

Most list endpoints take limit (default 50, max 500) and offset query parameters and echo limit, offset and total; /alerts differs (see API: Alerts):

{
  "servers": [...],
  "limit": 50,
  "offset": 0
}

To fetch the next page, add limit to offset. A page shorter than limit is the last one.

Tips

All Vigilhold docs · Start a 14-day free trial