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
- The OpenAPI 3.1 spec is available at /api/openapi.json — import it into Postman or Insomnia.
- Scope your keys tightly. A Slack alerting bot only needs alerts:read.