Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
openapi: 3.2.0
info:
title: Vigil Config API
description: 'Uptime, API checks with assertions, cron heartbeats, SSL expiry, website change detection and status pages.
Authenticate with `Authorization: Bearer ` (find your key under Settings). API access requires a paid plan.
Alert integration recipes: Spike.sh (webhook body template with `"source": "vigil"`), Apprise (send Apprise notifications into alert ingestion), MCP server, OpenTelemetry.'
version: 1.0.0
tags:
- name: Config
paths:
/api/v1/config:
get:
tags:
- Config
summary: Export monitors as code
description: '**Monitors as code.** Returns every monitor in the workspace as a desired-state document you can commit to git:
```yaml
version: 1
channels: [{name: Ops Telegram, kind: telegram}] # names only, no secrets
monitors:
- {name: Marketing site, mode: uptime, url: https://example.com, interval_minutes: 5, channels: [Ops Telegram], ...}
```
Each monitor lists the fields relevant to its mode (see `GET /api/v1/config/example` for a commented file). Feed the
document back with `PUT /api/v1/config` to apply changes. Requires a Business or Enterprise plan.'
operationId: export_config_api_v1_config_get
parameters:
- name: format
in: query
required: false
schema:
type: string
pattern: ^(yaml|json)$
default: yaml
title: Format
responses:
'200':
description: Successful Response
content:
application/x-yaml: {}
application/json: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
put:
tags:
- Config
summary: Apply a monitors-as-code file (desired state)
description: '**Monitors as code.** Send the YAML (`Content-Type: application/x-yaml`) or JSON (`application/json`) document from
`GET /api/v1/config`, edited to the state you want. Monitors are matched by `name`:
* missing monitors are **created**,
* existing monitors get the fields present in the file **updated** (keys you leave out are untouched),
* with `?prune=1`, monitors not in the file are **deleted** (channels are never deleted),
* `?dry_run=1` returns the plan without writing.
Every entry is validated first (same rules as the UI: plan limits, URL policy, cron syntax, assertion syntax, channel
names). If anything fails the response is `422` with `errors: [{name, error}]` and **nothing is applied**.
Response: `{"created": [...], "updated": [...], "deleted": [...], "unchanged": [...], "errors": [...], "dry_run": bool}`.
Requires a Business or Enterprise plan. Ideal for CI: run with `dry_run=1` on pull requests, apply on merge.'
operationId: apply_config_api_v1_config_put
parameters:
- name: dry_run
in: query
required: false
schema:
type: boolean
description: Validate and report the plan without writing anything
default: false
title: Dry Run
description: Validate and report the plan without writing anything
- name: prune
in: query
required: false
schema:
type: boolean
description: Delete monitors that are not listed in the file
default: false
title: Prune
description: Delete monitors that are not listed in the file
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/v1/config/example:
get:
tags:
- Config
summary: Commented example config file
description: 'A commented YAML file showing every monitor mode and its fields. Save it as `monitors.yml`, edit, and apply with
`PUT /api/v1/config`.'
operationId: example_config_api_v1_config_example_get
responses:
'200':
description: Successful Response
content:
text/plain:
schema:
type: string
components:
schemas:
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError