Skip to main content

endpulse

CI PyPI Python License: MIT

Multi-endpoint API health checks with assertions, SSL monitoring, and CI exit codes — in a single command.

pip install endpulse
$ endpulse https://api.example.com/health https://api.example.com/v2/status --ssl

┌──────────────────────────────────────────────────────────────────────────────────┐
│                              Endpoint Health Report                              │
├──────────────────────────────────┬────────┬──────┬──────────┬───────┬────────────┤
│ URL                              │ Status │ Code │ Time(ms) │ Size  │ SSL Expiry │
├──────────────────────────────────┼────────┼──────┼──────────┼───────┼────────────┤
│ https://api.example.com/health   │   UP   │ 200  │    42.5  │ 1.2KB │   89d      │
│ https://api.example.com/v2/status│   UP   │ 200  │   118.3  │ 2.4KB │   89d      │
└──────────────────────────────────┴────────┴──────┴──────────┴───────┴────────────┘

2/2 endpoints up  |  avg response: 80.4ms

Why endpulse?

Most HTTP tools are either one-shot clients (httpie, curl) or heavy infrastructure (k6, Uptime Kuma, Gatus).

endpulse fills the gap:

Feature curl/httpie k6/Artillery Uptime Kuma endpulse
Multi-endpoint in one command - - - yes
Response assertions (body, headers) - script UI CLI flags
CI/CD exit codes manual yes - yes
Watch mode (live terminal) - - web UI yes
SSL certificate monitoring - - yes yes
Webhook alerts (Slack/Discord) - plugin yes yes
Zero infrastructure yes yes no yes
YAML config - JS/YAML UI yes

Features

  • Async concurrent checks — semaphore-bounded, configurable concurrency
  • Response assertions — body contains, body regex, header match, status code
  • SSL certificate monitoring — check expiry dates with --ssl
  • Watch mode — continuous monitoring with live-updating terminal table
  • Webhook notifications — Slack, Discord, or generic webhook on failures
  • CI/CD integration — --fail flag returns exit code 1 on any failure
  • Multiple output formats — table, JSON, Markdown, CSV
  • YAML config — define endpoints, thresholds, headers, and assertions
  • Rich terminal output — color-coded status with timing and size
  • Cross-platform — Linux, macOS, Windows

Quick Start

# Check a single endpoint
endpulse https://api.example.com/health

# Check multiple endpoints with a slow threshold
endpulse https://api1.com https://api2.com --threshold 500

# Assert response body and fail CI if unhealthy
endpulse https://api.example.com/health --fail -a "body_contains:ok"

# Watch mode — re-check every 5 seconds
endpulse -c endpoints.yaml -w 5

# Generate a starter config file
endpulse --init

Usage

endpulse [OPTIONS] [URLS]...

Options:
  -c, --config PATH       YAML config file
  -n, --repeat INTEGER    Number of rounds  [default: 1]
  -t, --timeout FLOAT     Request timeout in seconds  [default: 10.0]
  --threshold FLOAT       Slow response threshold in ms  [default: 1000.0]
  --method TEXT            HTTP method  [default: GET]
  --concurrency INTEGER   Max concurrent requests  [default: 10]
  -o, --output FORMAT     Output: table|json|markdown|csv  [default: table]
  --json                  Output as JSON (shortcut)
  --fail                  Exit code 1 if any endpoint fails
  -a, --assert TEXT       Assertion (repeatable)
  -w, --watch FLOAT       Watch mode interval in seconds
  --ssl                   Check SSL certificate expiry
  --notify URL            Webhook URL for failure alerts (repeatable)
  --init                  Generate a sample endpoints.yaml
  --version               Show version and exit
  --help                  Show this message and exit

Assertions

Assert response content directly from the CLI:

# Body contains text
endpulse https://api.example.com -a "body_contains:ok"

# Body matches regex
endpulse https://api.example.com -a "body_regex:version.*\d+\.\d+"

# Header contains value
endpulse https://api.example.com -a "header_contains:content-type:json"

# Status code check
endpulse https://api.example.com -a "status:200"

# Multiple assertions — fail CI if any assertion fails
endpulse https://api.example.com -a "body_contains:ok" -a "status:200" --fail

SSL Certificate Monitoring

Check SSL certificate expiry alongside health checks:

# Check health + SSL expiry
endpulse https://api.example.com https://app.example.com --ssl

# SSL check in watch mode — catch expiring certs early
endpulse -c endpoints.yaml --ssl -w 3600

The SSL Expiry column shows days remaining. Certificates expiring within 14 days are flagged with (!).

Webhook Notifications

Get alerted on failures via Slack, Discord, or any webhook:

# Slack notification on failure
endpulse -c endpoints.yaml --notify https://hooks.slack.com/services/T00/B00/xxx

# Discord notification
endpulse -c endpoints.yaml --notify https://discord.com/api/webhooks/123/abc

# Multiple webhooks
endpulse -c endpoints.yaml \
  --notify https://hooks.slack.com/services/T00/B00/xxx \
  --notify https://example.com/webhook

# Watch mode with alerts — continuous monitoring with notifications
endpulse -c endpoints.yaml -w 30 --notify https://hooks.slack.com/services/T00/B00/xxx

Webhook type is auto-detected from the URL. Generic webhooks receive a JSON payload with full results.

You can also configure notifications in the YAML config:

notify:
  - https://hooks.slack.com/services/YOUR/WEBHOOK/URL

endpoints:
  - https://api.example.com/health

Output Formats

# Rich terminal table (default)
endpulse https://api.example.com

# JSON — pipe to jq or monitoring systems
endpulse https://api.example.com --output json

# Markdown — paste into GitHub Actions summary
endpulse -c endpoints.yaml --output markdown >> $GITHUB_STEP_SUMMARY

# CSV — import into spreadsheets or data tools
endpulse -c endpoints.yaml --output csv > results.csv

Config File

Generate a starter config:

endpulse --init

This creates endpoints.yaml in your current directory:

defaults:
  timeout: 10
  threshold_ms: 1000
  method: GET

notify:
  - https://hooks.slack.com/services/YOUR/WEBHOOK/URL

endpoints:
  - https://your-api.com/health

  - url: https://your-api.com/v2/status
    method: GET
    timeout: 5
    threshold_ms: 500
    assert:
      - "body_contains:ok"
      - "status:200"

  - url: https://your-api.com/webhook
    method: POST
    expected_status: 201
endpulse -c endpoints.yaml --fail

CI/CD Integration

GitHub Actions

- name: Health check
  run: |
    pip install endpulse
    endpulse -c endpoints.yaml --fail

# With Markdown summary
- name: Health check with report
  run: |
    pip install endpulse
    endpulse -c endpoints.yaml --output markdown --ssl >> $GITHUB_STEP_SUMMARY
    endpulse -c endpoints.yaml --fail

GitLab CI

health_check:
  script:
    - pip install endpulse
    - endpulse -c endpoints.yaml --fail --output json > health-report.json
  artifacts:
    paths:
      - health-report.json

The --fail flag makes endpulse return exit code 1 when any endpoint is DOWN or fails an assertion — your pipeline stops on unhealthy services.

Watch Mode

Monitor endpoints continuously:

# Re-check every 5 seconds
endpulse https://api1.com https://api2.com -w 5

# Watch with failure alerting to Slack
endpulse -c endpoints.yaml -w 30 --fail \
  --notify https://hooks.slack.com/services/T00/B00/xxx

The terminal table updates in-place with each round. Press Ctrl+C to stop.

Development

git clone https://github.com/kimhinton/endpulse.git
cd endpulse
pip install -e ".[dev]"
pytest -v
ruff check endpulse/ tests/
mypy endpulse/

License

MIT

Metadata

Release files for endpulse 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for endpulse 0.3.0
File Size Uploaded Provenance Actions
endpulse-0.3.0.tar.gz 19.9 kB Without provenance Details for endpulse-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for endpulse 0.3.0
File Interpreter ABI Platform Actions
endpulse-0.3.0-py3-none-any.whl Python 3 none any Details for endpulse-0.3.0-py3-none-any.whl

Total release size: 35.7 kB

Release files / endpulse-0.3.0.tar.gz

Download URL endpulse-0.3.0.tar.gz
Size 19.9 kB
Tags Source
SHA-256 checksum
How to use checksums
5f6c5daf3a669d78eeb514b7d40acf7dc9d11870aac705c58d1f45ca120e04e0
BLAKE2b-256 checksum
How to use checksums
1925d1ed8ff1dd35f182cbaf9f074329624e54611bca676789ef97108a099dbf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.9

Release files / endpulse-0.3.0-py3-none-any.whl

Download URL endpulse-0.3.0-py3-none-any.whl
Size 15.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ae08dff3db25d5a8e36daf1e070f42638bd622ca51812369ec8157c03cbfc980
BLAKE2b-256 checksum
How to use checksums
2ae3cdb03435c4d984dec4861da6e4eb9e724367b5c0279b1101875bc29b395b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.9

Security for endpulse 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page