Ping Happens API

Authentication

Client accounts (the ones created through Create account on the site) authenticate with a JSON Web Token. Log in or register to receive one:

POST/api/client-auth/register

Create a client account

Field	Type	Notes
`user`	string	Email address, must be unique
`name`	string	Display name
`password`	string	8+ characters, at least one letter and one number

Response: { token, client: { id, user } }

POST/api/client-auth

Field	Type
`user`	string
`password`	string

Response: { token, client: { id, user } }

Send the token on every request that follows: Authorization: Bearer <token>. It expires 2 hours after login. It is also bound to the exact User-Agent header your client sent when logging in — send that same User-Agent value on every subsequent request, or the token will be rejected.

Ownership & visibility

You can always read and write your own services and rules.
You can never read or write another client's data through the API, even data belonging to a service marked public — public services are for the public status page on the website, not for anonymous or third-party API access. Fetch them from the site itself, or authenticate as the owner.
Administrators (staff accounts with the admin role) can read and write any client's data.

Client profile & services

GET/api/client-services/{clientId}

Get a client's profile and services

Returns the client's profile and the list of their services, with a check-status summary for each. Only the account owner or an admin receives every service and the account email; anyone else gets neither.

Services

POST/api/services

Create a service

Field	Type	Notes
`userId`	string	Your client ID
`user`	string	Your account email
`resource`	string	Service display name
`public`	boolean	Defaults to `false`. See Ownership & visibility
`rule`	array	One or more rule objects (can be empty)

GET/api/services/{id}

Get a service

Returns the service, its rules, and up to 300 recent check results per rule. A rule's configuration (headers, payload, action) is only included for the owner or an admin.

PATCH/api/services/{id}

Rename a service

Field	Type
`resource`	string

DELETE/api/services/{id}

Delete a service

Also deletes the service's check history. This cannot be undone.

Rules

POST/api/services/{id}/rules

Add a rule to a service

Body: a rule object.

PATCH/api/services/{id}/rules/{ruleId}

Update a rule

Body: any subset of a rule object's fields.

DELETE/api/services/{id}/rules/{ruleId}

Delete a rule

Removes the rule. Its past check history is kept with the service.

Rule object

Field	Type	Notes
`url`	string	Target URL to check, required
`method`	string	`GET` \| `POST` \| `PUT` \| `DELETE`
`cron`	string	Cron expression, defaults to every 5 minutes
`active`	boolean	Defaults to `true`
`attemptsByAccess`	number	Retries per check, 1–3
`attemptsDelay`	number	Delay between retries in ms, 1–5000
`auth`	string	Optional bearer token sent to the target. Write-only — never returned; omit to leave an existing one unchanged
`headers`	array of `{ name, value }`	Extra request headers
`payload`	object	JSON request body, for non-`GET` methods
`action`	object or `null`	Optional webhook, fired when a check's status code matches. Shape: `{ url, statusCode: number[], headers?, auth? }`

Errors

Status	Meaning
400	The request body failed validation. The response body includes an `error` message.
401	Missing, invalid, or insufficient credentials for this resource.
404	Not found — also returned instead of 401 for a private resource you don't own, so its existence isn't revealed.
500	Unexpected server error.