pathly

README

Pathly Go SDK

English · Français · Español

Get started in one click. Create a free account on Pathly (sign up), create an API key in the console, then export PATHLY_API_TOKEN. This project is the official bridge to Pathly monitoring — real-browser and HTTP checks for checkout, login and availability, with data hosted in the EU. Full API reference: pathlyhq.com/en/developers.

Official Go client for the Pathly public /v1 API. Wire Pathly monitoring into your services, workers and CI: HTTP scenarios, maintenance windows, signed webhooks and SLA targets.

• Product: pathlyhq.com
• Developers (EN): pathlyhq.com/en/developers
• Developers (FR): pathlyhq.com/fr/developers
• API host: https://api.pathlyhq.com

go get github.com/pathlyhq/pathly-sdk-go
export PATHLY_API_TOKEN="sp_…"

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/pathlyhq/pathly-sdk-go"
)

func main() {
	client, err := pathly.New() // reads PATHLY_API_TOKEN
	if err != nil {
		log.Fatal(err)
	}
	name := "Checkout"
	url := "https://shop.example.com/cart"
	interval := int64(300)
	sc, err := client.CreateScenario(context.Background(), pathly.ScenarioInput{
		Name:        &name,
		URL:         &url,
		IntervalSec: &interval,
	}, "")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(sc.ID)
}

Why Pathly monitoring

Pathly is EU-hosted synthetic monitoring for the journeys your customers actually take. Use this SDK when you want the same Pathly monitoring controls as the console, from Go:

Need	Link
Product overview	pathlyhq.com
API & SDK docs (EN)	pathlyhq.com/en/developers
API & SDK docs (FR)	pathlyhq.com/fr/developers
Status & uptime story	Pathly monitoring on pathlyhq.com

Authentication

Variable	Purpose
PATHLY_API_TOKEN	Organization API key (sp_ prefix). Required.
PATHLY_API_URL	API base. Defaults to https://api.pathlyhq.com.

Never hard-code the token. Prefer the environment or a secret store.

Client.Ping calls GET /v1/usage and accepts HTTP 403: the key is valid but lacks org:read. That keeps least privilege for scenario-only keys.

Scopes: scenarios:read/write, alerting:read/write, maintenance:read/write, sla:read/write. Details on pathlyhq.com/en/developers.

Resources

Resource	Methods
Scenario (HTTP)	CreateScenario, GetScenario, UpdateScenario, DeleteScenario, ListScenarios, MuteScenario
Maintenance window	CreateMaintenanceWindow, GetMaintenanceWindow, DeleteMaintenanceWindow, ListMaintenanceWindows
Webhook	CreateWebhook, GetWebhook, DeleteWebhook, ListWebhooks
SLA target	UpsertSlaTarget (PUT), GetSlaTarget, DeleteSlaTarget, ListSlaTargets

Browser journeys are not managed here: create them in the Pathly console. This package is for HTTP Pathly monitoring scenarios only.

The webhook secret is returned once at creation. Store it in a vault. The API never returns the destination URL on read, only urlFingerprint.

Behavior

• Creates send an Idempotency-Key (auto-generated unless you pass one).
• HTTP 429 and 5xx honour Retry-After (capped at 90 seconds, four attempts).
• HTTP 404 is detectable with pathly.IsNotFound(err).
• Zero third-party runtime dependencies (stdlib only).

Development

go test -cover ./...

Coverage is required at 100%.

See examples/complete and the API reference on pathlyhq.com/en/developers (FR).

Related packages

Package	Role
pathly-terraform-provider	Terraform / OpenTofu
pathly-sdk-typescript	@pathlyhq/sdk
pathly-sdk-python	pathly
pathly-sdk-php	pathlyhq/sdk
Pathly product	Pathly monitoring

About Pathly

Pathly is synthetic monitoring for agencies and e-commerce: replay the customer journey, catch broken checkouts before your clients call, and keep evidence (screenshot, step, runbook) ready for the invoice. Product: pathlyhq.com · Developers: pathlyhq.com/en/developers · Status & pricing: pathlyhq.com/en/pricing.

Author

Company	Pathly
Author	Simon Raynaud / keyral

See AUTHORS. Homepage: pathlyhq.com.

License

Apache-2.0

Documentation

Overview

Package pathly is the official Go client for the Pathly public `/v1` API (https://pathlyhq.com — docs: https://pathlyhq.com/en/developers).

Hand-written rather than generated: creates stay idempotent, Retry-After is honoured, and a missing resource (404) stays distinct from a transport failure.

Index

• Constants
• func IsNotFound(err error) bool
• type APIError
  • func (e *APIError) Error() string
  • func (e *APIError) IsNotFound() bool
• type Client
  • func New(opts ...Option) (*Client, error)
  • func (c *Client) CreateMaintenanceWindow(ctx context.Context, in MaintenanceWindowInput, idempotencyKey string) (*MaintenanceWindow, error)
  • func (c *Client) CreateScenario(ctx context.Context, in ScenarioInput, idempotencyKey string) (*Scenario, error)
  • func (c *Client) CreateWebhook(ctx context.Context, in WebhookInput, idempotencyKey string) (*Webhook, error)
  • func (c *Client) DeleteMaintenanceWindow(ctx context.Context, id string) error
  • func (c *Client) DeleteScenario(ctx context.Context, id string) error
  • func (c *Client) DeleteSlaTarget(ctx context.Context, id string) error
  • func (c *Client) DeleteWebhook(ctx context.Context, id string) error
  • func (c *Client) GetMaintenanceWindow(ctx context.Context, id string) (*MaintenanceWindow, error)
  • func (c *Client) GetScenario(ctx context.Context, id string) (*Scenario, error)
  • func (c *Client) GetSlaTarget(ctx context.Context, id string) (*SlaTarget, error)
  • func (c *Client) GetWebhook(ctx context.Context, id string) (*Webhook, error)
  • func (c *Client) ListMaintenanceWindows(ctx context.Context) ([]MaintenanceWindow, error)
  • func (c *Client) ListScenarios(ctx context.Context) ([]Scenario, error)
  • func (c *Client) ListSlaTargets(ctx context.Context) ([]SlaTarget, error)
  • func (c *Client) ListWebhooks(ctx context.Context) ([]Webhook, error)
  • func (c *Client) MuteScenario(ctx context.Context, id string, until *string) error
  • func (c *Client) Ping(ctx context.Context) error
  • func (c *Client) UpdateScenario(ctx context.Context, id string, in ScenarioInput) (*Scenario, error)
  • func (c *Client) UpsertSlaTarget(ctx context.Context, in SlaTargetInput, idempotencyKey string) (*SlaTarget, error)
• type MaintenanceWindow
• type MaintenanceWindowInput
• type Option
  • func WithBaseURL(base string) Option
  • func WithHTTPClient(h *http.Client) Option
  • func WithSleep(f func(time.Duration)) Option
  • func WithToken(token string) Option
  • func WithUserAgent(ua string) Option
• type Scenario
• type ScenarioInput
• type SlaTarget
• type SlaTargetInput
• type Webhook
• type WebhookInput

Constants

const (
	// Version is the SDK semver (also used in the default User-Agent).
	Version = "0.1.0"

	// DefaultBaseURL is the production API.
	DefaultBaseURL = "https://api.pathlyhq.com"
)

Functions

func IsNotFound

func IsNotFound(err error) bool

IsNotFound is true when the error reports a missing resource.

Types

type APIError

type APIError struct {
	StatusCode int
	Message    string
	Path       string
}

APIError carries the status and the message returned by the API.

The API messages are written to be displayed as they are: rewording them would lose the detail that makes the fix possible (the named missing scope, the offending field, the exceeded limit).

func (*APIError) Error

func (e *APIError) Error() string

func (*APIError) IsNotFound

func (e *APIError) IsNotFound() bool

IsNotFound reports a resource missing from this organization.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is ready to use and safe for concurrent use. The token is never logged.

func New

func New(opts ...Option) (*Client, error)

New builds a client. Token defaults to PATHLY_API_TOKEN; base URL to PATHLY_API_URL or DefaultBaseURL.

func (*Client) CreateMaintenanceWindow

func (c *Client) CreateMaintenanceWindow(ctx context.Context, in MaintenanceWindowInput, idempotencyKey string) (*MaintenanceWindow, error)

CreateMaintenanceWindow creates a maintenance window.

func (*Client) CreateScenario

func (c *Client) CreateScenario(ctx context.Context, in ScenarioInput, idempotencyKey string) (*Scenario, error)

CreateScenario creates an HTTP scenario. An Idempotency-Key is always sent.

func (*Client) CreateWebhook

func (c *Client) CreateWebhook(ctx context.Context, in WebhookInput, idempotencyKey string) (*Webhook, error)

CreateWebhook creates a signed outbound webhook. Store Secret immediately.

func (*Client) DeleteMaintenanceWindow

func (c *Client) DeleteMaintenanceWindow(ctx context.Context, id string) error

DeleteMaintenanceWindow removes a window.

func (*Client) DeleteScenario

func (c *Client) DeleteScenario(ctx context.Context, id string) error

DeleteScenario removes a scenario.

func (*Client) DeleteSlaTarget

func (c *Client) DeleteSlaTarget(ctx context.Context, id string) error

DeleteSlaTarget removes an SLA target.

func (*Client) DeleteWebhook

func (c *Client) DeleteWebhook(ctx context.Context, id string) error

DeleteWebhook removes a webhook.

func (*Client) GetMaintenanceWindow

func (c *Client) GetMaintenanceWindow(ctx context.Context, id string) (*MaintenanceWindow, error)

GetMaintenanceWindow reads one window by id.

func (*Client) GetScenario

func (c *Client) GetScenario(ctx context.Context, id string) (*Scenario, error)

GetScenario reads one scenario by id.

func (*Client) GetSlaTarget

func (c *Client) GetSlaTarget(ctx context.Context, id string) (*SlaTarget, error)

GetSlaTarget reads one SLA target by id.

func (*Client) GetWebhook

func (c *Client) GetWebhook(ctx context.Context, id string) (*Webhook, error)

GetWebhook reads one webhook by id (URL never returned, only fingerprint).

func (*Client) ListMaintenanceWindows

func (c *Client) ListMaintenanceWindows(ctx context.Context) ([]MaintenanceWindow, error)

ListMaintenanceWindows lists every page of maintenance windows.

func (*Client) ListScenarios

func (c *Client) ListScenarios(ctx context.Context) ([]Scenario, error)

ListScenarios walks every page of HTTP scenarios.

func (*Client) ListSlaTargets

func (c *Client) ListSlaTargets(ctx context.Context) ([]SlaTarget, error)

ListSlaTargets lists every page of SLA targets.

func (*Client) ListWebhooks

func (c *Client) ListWebhooks(ctx context.Context) ([]Webhook, error)

ListWebhooks lists every page of webhooks.

func (*Client) MuteScenario

func (c *Client) MuteScenario(ctx context.Context, id string, until *string) error

MuteScenario mutes or unmutes. A nil until wakes the scenario up.

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) error

Ping checks that the token is accepted.

A 403 is not a failure: it proves the key is valid and only signals that it does not carry org:read. Treating that as an error would force every scenario-only key to request an organization scope.

func (*Client) UpdateScenario

func (c *Client) UpdateScenario(ctx context.Context, id string, in ScenarioInput) (*Scenario, error)

UpdateScenario patches an existing scenario.

func (*Client) UpsertSlaTarget

func (c *Client) UpsertSlaTarget(ctx context.Context, in SlaTargetInput, idempotencyKey string) (*SlaTarget, error)

UpsertSlaTarget creates or replaces an SLA target (PUT).

type MaintenanceWindow

type MaintenanceWindow struct {
	ID          string  `json:"id"`
	MonitorID   *string `json:"monitorId"`
	StartsAt    *string `json:"startsAt"`
	EndsAt      *string `json:"endsAt"`
	Reason      *string `json:"reason"`
	Weekday     *int64  `json:"weekday"`
	StartMinute *int64  `json:"startMinute"`
	DurationMin *int64  `json:"durationMin"`
}

MaintenanceWindow is a planned silence window for a scenario.

type MaintenanceWindowInput

type MaintenanceWindowInput struct {
	MonitorID   *string `json:"monitorId,omitempty"`
	StartsAt    *string `json:"startsAt,omitempty"`
	EndsAt      *string `json:"endsAt,omitempty"`
	Reason      *string `json:"reason,omitempty"`
	Weekday     *int64  `json:"weekday,omitempty"`
	StartMinute *int64  `json:"startMinute,omitempty"`
	DurationMin *int64  `json:"durationMin,omitempty"`
}

MaintenanceWindowInput is the write payload for a maintenance window.

type Option

type Option func(*Client)

Option configures the client at construction time.

func WithBaseURL

func WithBaseURL(base string) Option

WithBaseURL overrides the API base URL.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient forces an HTTP client, for tests or a corporate proxy.

func WithSleep

func WithSleep(f func(time.Duration)) Option

WithSleep replaces the wait between two attempts (tests inject a no-op).

func WithToken

func WithToken(token string) Option

WithToken sets the API token explicitly.

func WithUserAgent

func WithUserAgent(ua string) Option

WithUserAgent identifies the SDK version in the API logs.

type Scenario

type Scenario struct {
	ID                  string   `json:"id"`
	Name                string   `json:"name"`
	Type                string   `json:"type"`
	URL                 *string  `json:"url"`
	Enabled             *bool    `json:"enabled"`
	IntervalSec         *int64   `json:"intervalSec"`
	Method              *string  `json:"method"`
	ExpectedStatus      *int64   `json:"expectedStatus"`
	MaxLatencyMs        *int64   `json:"maxLatencyMs"`
	ExpectText          *string  `json:"expectText"`
	Runbook             *string  `json:"runbook"`
	Cron                *string  `json:"cron"`
	LastStatus          *string  `json:"lastStatus"`
	Regions             []string `json:"regions"`
	Tags                []string `json:"tags"`
	Folder              *string  `json:"folder"`
	Severity            *string  `json:"severity"`
	MutedUntil          *string  `json:"mutedUntil"`
	ScenarioFingerprint *string  `json:"scenarioFingerprint"`
	CreatedAt           *string  `json:"createdAt"`
}

Scenario mirrors the public projection of an HTTP monitoring scenario.

type ScenarioInput

type ScenarioInput struct {
	Name           *string  `json:"name,omitempty"`
	Type           *string  `json:"type,omitempty"`
	URL            *string  `json:"url,omitempty"`
	IntervalSec    *int64   `json:"intervalSec,omitempty"`
	Method         *string  `json:"method,omitempty"`
	ExpectedStatus *int64   `json:"expectedStatus,omitempty"`
	MaxLatencyMs   *int64   `json:"maxLatencyMs,omitempty"`
	ExpectText     *string  `json:"expectText,omitempty"`
	Regions        []string `json:"regions,omitempty"`
	Tags           []string `json:"tags,omitempty"`
	Folder         *string  `json:"folder,omitempty"`
	Severity       *string  `json:"severity,omitempty"`
	Runbook        *string  `json:"runbook,omitempty"`
	Cron           *string  `json:"cron,omitempty"`
	Enabled        *bool    `json:"enabled,omitempty"`
}

ScenarioInput serves both create and update. Absent pointer fields are not sent so the API keeps the existing value.

type SlaTarget

type SlaTarget struct {
	ID                 string   `json:"id"`
	MonitorID          *string  `json:"monitorId"`
	Name               *string  `json:"name"`
	ObjectivePct       *float64 `json:"objectivePct"`
	WindowDays         *int64   `json:"windowDays"`
	ExcludeMaintenance *bool    `json:"excludeMaintenance"`
	WarnAtBudgetRatio  *float64 `json:"warnAtBudgetRatio"`
	Enabled            *bool    `json:"enabled"`
}

SlaTarget is an availability objective bound to a scenario.

type SlaTargetInput

type SlaTargetInput struct {
	MonitorID          *string  `json:"monitorId,omitempty"`
	Name               *string  `json:"name,omitempty"`
	ObjectivePct       float64  `json:"objectivePct"`
	WindowDays         int64    `json:"windowDays"`
	ExcludeMaintenance *bool    `json:"excludeMaintenance,omitempty"`
	WarnAtBudgetRatio  *float64 `json:"warnAtBudgetRatio,omitempty"`
	Enabled            *bool    `json:"enabled,omitempty"`
}

SlaTargetInput creates or replaces an SLA target (PUT upsert).

type Webhook

type Webhook struct {
	ID             string   `json:"id"`
	Events         []string `json:"events"`
	Enabled        *bool    `json:"enabled"`
	HasSecret      *bool    `json:"hasSecret"`
	URLFingerprint *string  `json:"urlFingerprint"`
	CreatedAt      *string  `json:"createdAt"`
	Secret         *string  `json:"secret"`
}

Webhook is an outbound signed webhook. The destination URL is never returned on read — only urlFingerprint. Secret is filled only on create.

type WebhookInput

type WebhookInput struct {
	URL    string   `json:"url"`
	Events []string `json:"events,omitempty"`
}

WebhookInput creates an outbound webhook.