Black Friday in 17 days: will your customers be able to pay? 25% off the first year and free setup, until 30 NovemberSee the offer →
PathIntegration
Developers documentation
API /v1, Terraform, HMAC webhooks and SDKs. Pick a page on the left, or follow the quickstart.
Get my API keyOpenAPI contract
Full document, no authentication, ready for your client generator.
# PATHLY_API_TOKEN comes from CI secrets, never from the code
curl -sS -X POST https://api.pathlyhq.com/v1/scenarios \
-H "Authorization: Bearer $PATHLY_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"type": "http", "name": "Home", "url": "https://www.example.com/", "intervalSec": 300}'Keep PATHLY_API_TOKEN in your CI secrets, never in the repository.
Get started
- 5 minREST APIOne key, one Ping created with cURL, the list of runs.
- 10 minTerraformThe pathlyhq/pathly provider versions Ping, Chain and webhooks.
- 10 minGitHub ActionReplays a journey after deploy and fails the job if it breaks.
- 15 minHMAC webhooksReceive every failure signed, and check the signature in a few lines.
Mental model
- ScenarioA Ping, Flow or Chain, created in the console, through the API or Terraform.
- RunPathly replays it from Europe, on a schedule or on demand from CI.
- IncidentA confirmed failure opens an incident, with the step screenshot.
- WebhookYour system receives the HMAC-signed event.
In detail
Pathly exposes a versioned public API under https://api.pathlyhq.com/v1. An organisation owns scenarios, runs, incidents, webhooks, maintenance windows and availability targets. Console and API share one configuration truth: what you create here appears there, and the other way around.
Two ways in, one stack: business records a Flow in the console; engineering versions Ping, Chain, webhooks and SLAs via IaC or SDK. A Chain is created with `httpChain` on POST /v1/scenarios (login → API hops). Flow secrets must never enter Terraform state or a Git repo.
The OpenAPI contract the platform serves is the source of truth for routes. This page loads it at render: a removed route disappears from the reference below on its own.
5-minute quickstart
Goal: one key, one Ping, one test webhook, one Terraform pointer. About five minutes if the Solo account already exists. A Chain is then created with httpChain (API) or http_chain (provider).
1) Open the Pathly Console (create a free account via the link below) → Settings → API keys → issue a key with scenarios:write and alerting:write. Copy the secret once (sp_ prefix). 2) Export PATHLY_API_TOKEN. 3) Create the scenario (example below). 4) Create a webhook to a test sink (webhook.site or your /hooks). 5) Terraform provider pathlyhq/pathly to version the rest.
1 — Auth + list
export PATHLY_API_TOKEN=sp_…
curl -sS https://api.pathlyhq.com/v1/scenarios \
-H "Authorization: Bearer $PATHLY_API_TOKEN" | jq .2 — Create a Ping (idempotent)
curl -sS -X POST https://api.pathlyhq.com/v1/scenarios \
-H "Authorization: Bearer $PATHLY_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: qs-$(date +%Y%m%d)-home" \
-d '{
"type": "http",
"name": "Home",
"url": "https://www.example.com/",
"intervalSec": 300,
"expectedStatus": 200
}'3 — Signed outbound webhook
curl -sS -X POST https://api.pathlyhq.com/v1/webhooks \
-H "Authorization: Bearer $PATHLY_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: qs-hook-1" \
-d '{
"url": "https://www.example.com/hooks/pathly",
"events": ["run.failed", "run.recovered"]
}'4 — Terraform
terraform {
required_providers {
pathly = { source = "pathlyhq/pathly", version = "~> 0.1" }
}
}
provider "pathly" {}
# PATHLY_API_TOKEN in the CI / shell environment, never in .tf filesDoc pages
Authentication and API keys
Bearer, TTL, storing PATHLY_API_TOKEN — never exposing the key in Git.
Open →Scopes and least privilege
resource:action matrix, write→read implication, and separate keys per CI use case.
Open →HTTP contract: rate limits, idempotency, errors
Retry-After, Idempotency-Key, cursors and 4xx codes — stable behaviour to implement once.
Open →Ping, Flow, Chain — runs, incidents and SLA
Ping vs Flow vs Chain, triggering runs, maintenance and availability targets.
Open →HMAC-signed outbound webhooks
run.failed / run.recovered events, X-Pathly-* headers and signature verification.
Open →Pathly Terraform and OpenTofu
Provider pathlyhq/pathly: scenarios, webhooks, maintenance and SLA as code.
Open →Pathly integrations catalog
One /v1 API, one PATHLY_API_TOKEN — each tool has its own examples page.
Open →TypeScript / JavaScript SDK @pathly/sdk
Official npm client: create scenarios, paginate, Idempotency-Key and Retry-After.
Open →Pathly Python SDK (PyPI)
pip install pathly — typed stdlib client for Lambda, Cloud Run and cron.
Open →Pathly Go SDK
Module github.com/pathlyhq/pathly-sdk-go — idempotency and Retry-After like the Terraform provider.
Open →Pathly PHP SDK (Composer)
composer require pathlyhq/sdk — PHP 8.1+, PSR-4, for Symfony, Laravel and hoster scripts.
Open →Pathly Ruby SDK
Gem pathly from GitHub — same /v1 API as the other official clients.
Open →Pathly Pulumi (@pathly/pulumi)
Monitoring as code in TypeScript via Pulumi, wired to the same API as Terraform.
Open →Pathly CDK for Terraform
npm @pathly/cdktf — typed Terraform on top of provider pathlyhq/pathly.
Open →Pathly Ansible collection
Modules pathly_scenario, webhook, maintenance and SLA — idempotent, token out of the playbook.
Open →Pathly GitHub Action (pathly-action)
Post-deploy smoke: run-scenario fails the job if the run is not ok. Alias run-and-wait.
Open →Pathly GitLab CI components
pathly-ping and pathly-scenario in the GitLab catalog — red pipeline if the smoke fails.
Open →Pathly Kubernetes operator and Crossplane
PathlyScenario CRDs, GHCR images, token in a cluster Secret.
Open →Pathly Postman collection
Explore /v1 without code: GitHub import, baseUrl + apiToken environment.
Open →Cookbook, EU security and drift
for_each recipes, CI smoke, webhook verify, GDPR and UI-or-Terraform rule.
Open →/v1 route reference
List loaded from the OpenAPI contract at render — a removed route disappears on its own.
Open →