Use API tokens, the REST API and the monctl CLI

The REST API lets scripts, CI pipelines and the monctl CLI work with your workspace. API access is included on every plan, and an OpenAPI specification describes every endpoint.

Create a token

Go to Settings → API tokens. Under Create a token, choose a Name, the Scopes (Read is always included; tick Write to create and change monitors, incidents and deployments) and Expires after (days). Copy the token right away and store it as a secret, for example in your CI. It will not be shown again; if you lose it, revoke it and create a new one.

Tokens act with their creator's permissions in this workspace only, and cannot manage other tokens. The token list shows when each token was last used, and admins can Revoke a token at any time. Your workspace id is shown under Settings → Workspace.

Call the API

export MONITORING_URL=https://uptimetracker.live
export MONITORING_WORKSPACE=your-workspace-id
export MONITORING_TOKEN=mon_...

curl -fsS "$MONITORING_URL/api/v1/workspaces/$MONITORING_WORKSPACE/monitors" \
  -H "Authorization: Bearer $MONITORING_TOKEN"

Tokens are limited to 300 requests per minute.

The monctl CLI

monctl is a small command-line client. It reads MONITORING_URL, MONITORING_TOKEN and MONITORING_WORKSPACE from the environment, or the --url, --token and --workspace flags. Add --json for raw JSON output.

monctl monitors list
monctl monitors create --name API --target https://api.example.com/health --interval 60
monctl monitors pause <monitor-id>
monctl monitors resume <monitor-id>
monctl incidents list
monctl incidents ack <incident-id>
monctl maintenance add --monitor <monitor-id> --minutes 30 --note "Deploy"
monctl deploy --service checkout --version v2.4.1 --env production --tag checkout --maintenance 10
monctl export monitors > monitors.csv

Deployment markers from CI

On Starter and Team, record each deployment so incidents shortly after it show the deploy as "possibly related". A marker can also open a maintenance window of up to 30 minutes. Use a token with the Write scope. GitHub Actions example:

- name: Record deployment
  if: success()
  run: |
    curl -fsS -X POST "$MONITORING_URL/api/v1/workspaces/$MONITORING_WORKSPACE/deployments" \
      -H "Authorization: Bearer $MONITORING_TOKEN" -H "Content-Type: application/json" \
      -d "{\"service\":\"checkout\",\"version\":\"$GITHUB_SHA\",\"source\":\"github\",\"tags\":[\"checkout\"],\"maintenance_minutes\":10}"
  env:
    MONITORING_URL: https://uptimetracker.live
    MONITORING_WORKSPACE: ${{ vars.MONITORING_WORKSPACE }}
    MONITORING_TOKEN: ${{ secrets.MONITORING_TOKEN }}

The body accepts service and version (required), plus optional environment (default production), source, url, monitor_ids, tags, project_id and maintenance_minutes (1 to 30). The same pattern works in GitLab CI and Jenkins. Deployment markers are listed under Settings → Deployments.

Security tips

• Give every token an expiry and use Read-only tokens for dashboards and reports.
• Create CI tokens as a member whose permissions match what the pipeline needs.
• Revoke tokens you no longer use.