Version:
With the Management API, you can programmatically manage checks and integrations in your account.
| Endpoint Name | Endpoint Address |
|---|---|
| Checks | |
| List existing checks | GET https://hc.framasoft.org/api/v3/checks/ |
| Get a single check | GET https://hc.framasoft.org/api/v3/checks/<uuid>GET https://hc.framasoft.org/api/v3/checks/<unique_key> |
| Create a new check | POST https://hc.framasoft.org/api/v3/checks/ |
| Update an existing check | POST https://hc.framasoft.org/api/v3/checks/<uuid> |
| Pause monitoring of a check | POST https://hc.framasoft.org/api/v3/checks/<uuid>/pause |
| Resume monitoring of a check | POST https://hc.framasoft.org/api/v3/checks/<uuid>/resume |
| Delete check | DELETE https://hc.framasoft.org/api/v3/checks/<uuid> |
| Pings | |
| List check's logged pings | GET https://hc.framasoft.org/api/v3/checks/<uuid>/pings/ |
| Get a ping's logged body | GET https://hc.framasoft.org/api/v3/checks/<uuid>/pings/<n>/body |
| Flips | |
| List check's status changes | GET https://hc.framasoft.org/api/v3/checks/<uuid>/flips/GET https://hc.framasoft.org/api/v3/checks/<unique_key>/flips/ |
| Integrations | |
| List existing integrations | GET https://hc.framasoft.org/api/v3/channels/ |
| Badges | |
| List project's badges | GET https://hc.framasoft.org/api/v3/badges/ |
| Service status | |
| Check database connectivity | GET https://hc.framasoft.org/api/v3/status/ |
Management API v3 adds the ability to specify custom check slugs, instead of
auto-generating them from check names. The Create a new check
and Update an existing check calls accept a new slug
parameter, and use it instead of generating the slug from the check's name.
Your requests to Framasoft cron’s health checks Management API must authenticate using an API key. All API keys are project-specific. There are no account-wide API keys. By default, a project on Framasoft cron’s health checks doesn't have an API key. You can create read-write and read-only API keys on the Project Settings page.
Only works with the following API endpoints:
Omits sensitive information from the API responses. See the documentation of individual API endpoints for details.
The client can authenticate itself by including an X-Api-Key: <your-api-key>
header in an HTTP request. Alternatively, for POST requests with a JSON request body,
the client can put an api_key field in the JSON document.
See the Create a new check section for an example.
For POST requests, the Framasoft cron’s health checks API expects the request body to be
a JSON document (not a multipart/form-data encoded form data).
Framasoft cron’s health checks uses HTTP status codes wherever possible. In general, 2xx class indicates success, 4xx indicates a client error, and 5xx indicates a server error.
The response may contain a JSON document with additional data.
GET https://hc.framasoft.org/api/v3/checks/
Returns a list of checks belonging to the user, optionally filtered by one or more tags.
Filters the checks and returns only the checks with the specified slug. If there are no matching checks, returns an empty list. If there are multiple matching checks, returns all of them.
Example:
https://hc.framasoft.org/api/v3/checks/?slug=backups
Filters the checks and returns only the checks that are tagged with the specified value.
This parameter can be repeated multiple times.
Example:
https://hc.framasoft.org/api/v3/checks/?tag=foo&tag=bar
curl --header "X-Api-Key: your-api-key" https://hc.framasoft.org/api/v3/checks/
{
"checks": [
{
"name": "Filesystem Backup",
"slug": "filesystem-backup",
"tags": "backup fs",
"desc": "Runs incremental backup every hour",
"grace": 600,
"n_pings": 1,
"status": "up",
"started": false,
"last_ping": "2020-03-24T14:02:03+00:00",
"next_ping": "2020-03-24T15:02:03+00:00",
"manual_resume": false,
"methods": "",
"start_kw": "START",
"success_kw": "SUCCESS",
"failure_kw": "ERROR",
"filter_subject": true,
"filter_body": false,
"uuid": "31365bce-8da9-4729-8ff3-aaa71d56b712",
"ping_url": "https://hc.framasoft.org/ping/31365bce-8da9-4729-8ff3-aaa71d56b712",
"update_url": "https://hc.framasoft.org/api/v3/checks/31365bce-8da9-4729-8ff3-aaa71d56b712",
"pause_url": "https://hc.framasoft.org/api/v3/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/pause",
"resume_url": "https://hc.framasoft.org/api/v3/checks/31365bce-8da9-4729-8ff3-aaa71d56b712/resume",
"channels": "1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c",
"timeout": 3600
},
{
"name": "Database Backup",
"slug": "database-backup",
"tags": "production db",
"desc": "Runs ~/db-backup.sh",
"grace": 1200,
"n_pings": 7,
"status": "down",
"started": false,
"last_ping": "2020-03-23T10:19:32+00:00",
"next_ping": null,
"manual_resume": false,
"methods": "",
"start_kw": "",
"success_kw": "",
"failure_kw": "",
"filter_subject": false,
"filter_body": false,
"uuid": "803f680d-e89b-492b-82ef-2be7b774a92d",
"ping_url": "https://hc.framasoft.org/ping/803f680d-e89b-492b-82ef-2be7b774a92d",
"update_url": "https://hc.framasoft.org/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d",
"pause_url": "https://hc.framasoft.org/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause",
"resume_url": "https://hc.framasoft.org/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d/resume",
"channels": "1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c",
"schedule": "15 5 * * *",
"tz": "UTC"
}
]
}
The possible values for the status field are: new, up, grace, down,
and paused.
When using the read-only API key, Framasoft cron’s health checks omits the following fields from responses:
uuid, ping_url, update_url, pause_url, resume_url, channels. It adds an
extra unique_key field. The unique_key identifier is stable across API calls, and
you can use it in the Get a single check
and List check's status changes API calls.
Example:
{
"checks": [
{
"name": "Filesystem Backup",
"slug": "filesystem-backup",
"tags": "backup fs",
"desc": "Runs incremental backup every hour",
"grace": 600,
"n_pings": 1,
"status": "up",
"started": false,
"last_ping": "2020-03-24T14:02:03+00:00",
"next_ping": "2020-03-24T15:02:03+00:00",
"manual_resume": false,
"methods": "",
"start_kw": "START",
"success_kw": "SUCCESS",
"failure_kw": "ERROR",
"filter_subject": true,
"filter_body": false,
"unique_key": "a6c7b0a8a66bed0df66abfdab3c77736861703ee",
"timeout": 3600
},
{
"name": "Database Backup",
"slug": "database-backup",
"tags": "production db",
"desc": "Runs ~/db-backup.sh",
"grace": 1200,
"n_pings": 7,
"status": "down",
"started": false,
"last_ping": "2020-03-23T10:19:32+00:00",
"next_ping": null,
"manual_resume": false,
"methods": "",
"start_kw": "",
"success_kw": "",
"failure_kw": "",
"filter_subject": false,
"filter_body": false,
"unique_key": "124f983e0e3dcaeba921cfcef46efd084576e783",
"schedule": "15 5 * * *",
"tz": "UTC"
}
]
}
GET https://hc.framasoft.org/api/v3/checks/<uuid>
GET https://hc.framasoft.org/api/v3/checks/<unique_key>
Returns a JSON representation of a single check. Accepts either check's UUID or
the unique_key (a field derived from UUID and returned by API responses when
using the read-only API key) as an identifier.
curl --header "X-Api-Key: your-api-key" https://hc.framasoft.org/api/v3/checks/<uuid>
{
"name": "Database Backup",
"slug": "database-backup",
"tags": "production db",
"desc": "Runs ~/db-backup.sh",
"grace": 1200,
"n_pings": 7,
"status": "down",
"started": false,
"last_ping": "2020-03-23T10:19:32+00:00",
"next_ping": null,
"manual_resume": false,
"methods": "",
"start_kw": "START",
"success_kw": "SUCCESS",
"failure_kw": "ERROR",
"filter_subject": true,
"filter_body": false,
"uuid": "803f680d-e89b-492b-82ef-2be7b774a92d",
"ping_url": "https://hc.framasoft.org/ping/803f680d-e89b-492b-82ef-2be7b774a92d",
"update_url": "https://hc.framasoft.org/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d",
"pause_url": "https://hc.framasoft.org/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d/pause",
"resume_url": "https://hc.framasoft.org/api/v3/checks/803f680d-e89b-492b-82ef-2be7b774a92d/resume",
"channels": "1bdea468-03bf-47b8-ab27-29a9dd0e4b94,51c6eb2b-2ae1-456b-99fe-6f1e0a36cd3c",
"schedule": "15 5 * * *",
"tz": "UTC"
}
The possible values for the status field are: new, up, grace, down,
and paused.
When using the read-only API key, Framasoft cron’s health checks omits the following fields from responses:
uuid, ping_url, update_url, pause_url, resume_url, channels. It adds an
extra unique_key field. This identifier is stable across API calls.
Note: although API omits the *_url fields in read-only API responses, the client can
easily construct these URLs themselves if they know the check's unique UUID.
{
"name": "Database Backup",
"slug": "database-backup",
"tags": "production db",
"desc": "Runs ~/db-backup.sh",
"grace": 1200,
"n_pings": 7,
"status": "down",
"started": false,
"last_ping": "2020-03-23T10:19:32+00:00",
"next_ping": null,
"manual_resume": false,
"methods": "",
"start_kw": "SUCCESS",
"success_kw": "SUCCESS",
"failure_kw": "ERROR",
"filter_subject": true,
"filter_body": false,
"unique_key": "124f983e0e3dcaeba921cfcef46efd084576e783",
"schedule": "15 5 * * *",
"tz": "UTC"
}
POST https://hc.framasoft.org/api/v3/checks/
Creates a new check and returns its ping URL. All request parameters are optional and will use their default values if omitted.
With this API call, you can create both Simple and Cron checks:
timeout parameter.schedule and tz parameters.string, optional, default value: ""
Name for the new check.
Changed in API v3: the check's slug is no longer automatically generated
from the check's name. Instead, the client can specify the slug explicitly
via the slug field.
string, optional, default value: ""
Slug for the new check. The slug should only contain the following
characters: a-z, 0-9, hyphens, underscores. Example:
{"slug": "my-custom-slug"}
string, optional, default value: ""
A space-delimited list of tags for the new check. Example:
{"tags": "reports staging"}
string, optional.
Description of the check.
number, optional, default value: 86400.
The expected period of this check in seconds.
Minimum: 60 (one minute), maximum: 31536000 (365 days).
Example for a 5-minute timeout:
{"timeout": 300}
number, optional, default value: 3600.
The grace period for this check in seconds.
Minimum: 60 (one minute), maximum: 31536000 (365 days).
string, optional.
A cron or systemd OnCalendar expression defining this check's schedule. Framasoft cron’s health checks will detect the expression type (cron or OnCalendar) automatically.
The schedule parameter takes precedence over the timeout field: if you specify
both the timeout and the schedule parameters, Framasoft cron’s health checks will save the
schedule and ignore the timeout.
Example using a cron expression ("run every half-hour"):
{"schedule": "0,30 * * * *"}
Example using an OnCalendar expression ("run at 12:00 of the last day of every month"):
{"schedule": "*-*~1 12:00"}
string, optional, default value: "UTC".
Server's timezone. This setting only has an effect in combination with the
schedule parameter.
Example:
{"tz": "Europe/Riga"}
boolean, optional, default value: false.
Controls whether a paused check automatically resumes when pinged (the default) or not. If set to false, a paused check will leave the paused state when it receives a ping. If set to true, a paused check will ignore pings and stay paused until you manually resume it from the web dashboard.
string, optional, default value: "".
Specifies the allowed HTTP methods for making ping requests. Must be one of the two values: "" (an empty string) or "POST".
Set this field to "" (an empty string) to allow HEAD, GET, and POST requests.
Set this field to "POST" to allow only POST requests.
Example:
{"methods": "POST"}
string, optional.
By default, this API call assigns no integrations to the newly created check.
Set this field to a special value "*" to automatically assign all existing integrations. Example:
{"channels": "*"}
To assign specific integrations, use a comma-separated list of integration UUIDs. You can look up integration UUIDs using the List Existing Integrations API call.
Example:
{"channels":
"4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc"}
Alternatively, if you have named your integrations in Framasoft cron’s health checks dashboard, you can specify integrations by their names. For this to work, your integrations need non-empty unique names, and they must not contain commas. The names must match exactly, whitespace is significant.
Example:
{"channels": "Email to Alice,SMS to Alice"}
array of string values, optional, default value: [].
Enables "upsert" functionality. Before creating a check, Framasoft cron’s health checks looks for
existing checks, filtered by fields listed in unique.
If Framasoft cron’s health checks does not find a matching check, it creates a new check and returns it with the HTTP status code 201.
If Framasoft cron’s health checks finds a matching check, it updates the existing check and returns it with HTTP status code 200.
The accepted values for the unique field are
name, slug, tags, timeout, and grace.
Example:
{"name": "Backups", unique: ["name"]}
In this example, if a check named "Backups" exists, it will be returned. Otherwise, a new check will be created and returned.
string, optional, default value: "".
Specifies the keywords for classifying inbound email messages as "Start" signals. Separate multiple keywords using commas.
Use this field in combination with the filter_subject and filter_body fields.
Setting filter_subject to true enables filtering on the email subject line,
filter_body enables filtering on the entire email body. Framasoft cron’s health checks supports both
plain text and HTML email messages.
Example:
{"filter_subject": true, "start_kw": "STARTED"}
In this example, Framasoft cron’s health checks classifies the email as a start signal if the Subject line contains the word "STARTED".
string, optional, default value: "".
Specifies the keywords for classifying inbound email messages as "Success" signals. Separate multiple keywords using commas.
Use this field in combination with the filter_subject and filter_body fields.
Setting filter_subject to true enables filtering on the email subject line,
filter_body enables filtering on the entire email body. Framasoft cron’s health checks supports both
plain text and HTML email messages.
Example:
{"filter_subject": true, "success_kw": "SUCCESS,COMPLETED"}
In this example, the email counts as success if the Subject line contains either the word "SUCCESS" or the word "COMPLETED".
string, optional, default value: "".
Specifies the keywords for classifying inbound email messages as "Failure" signals. Separate multiple keywords using commas.
Use this field in combination with the filter_subject and filter_body fields.
Setting filter_subject to true enables filtering on the email subject line,
filter_body enables filtering on the entire email body. Framasoft cron’s health checks supports both
plain text and HTML email messages.
Example:
{"filter_subject": true, "failure_kw": "FAILED, ERROR"}
In this example, the email counts as failure if the Subject line contains either the word "FAILED" or the word "ERROR".
boolean, optional, default value: false.
Enables filtering of inbound email messages by looking for keywords in their
subject lines. See also the success_kw and failure_kw fields.
boolean, optional, default value: false.
Enables filtering of inbound email messages by looking for keywords in their
message body. See also the success_kw and failure_kw fields.
string, optional, default value: "".
Deprecated. Use the success_kw, filter_subject and filter_body fields
instead.
Specifies the keywords for classifying inbound email messages as "Success" signals. Separate multiple keywords using commas. If any of the keywords is found in an email message's Subject line, the email message will count as "Success".
Set this field to "" (an empty string) to consider all inbound email messages as
"Success" (unless they match any keywords listed in subject_fail and are thus
classified as "Failure").
Example:
SUCCESS,COMPLETED
In this example, the email counts as success if the Subject line contains either the word "SUCCESS" or the word "COMPLETED".
string, optional, default value: "".
Deprecated. Use the failure_kw, filter_subject and filter_body fields
instead.
Specifies the keywords for classifying inbound email messages as "Failure" signals. Separate multiple keywords using commas. If any of the keywords is found in an email message's Subject line, the email message will count as "Failure".
Set this field to "" (an empty string) to perform no "Failure" classification.
Example:
FAILED,ERROR
In this example, the email counts as failure if the Subject line contains either the word "FAILED" or the word "ERROR".
curl https://hc.framasoft.org/api/v3/checks/ \
--header "X-Api-Key: your-api-key" \
--data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
Or, alternatively:
curl https://hc.framasoft.org/api/v3/checks/ \
--data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
{
"name": "Backups",
"slug": "",
"tags": "prod www",
"desc": "",
"grace": 60,
"n_pings": 0,
"status": "new",
"started": false,
"last_ping": null,
"next_ping": null,
"manual_resume": false,
"methods": "",
"subject": "",
"subject_fail": "",
"start_kw": "",
"success_kw": "",
"failure_kw": "",
"filter_subject": false,
"filter_body": false,
"uuid": "7918b17b-a745-4db1-8575-9d2e07c97f79",
"ping_url": "https://hc.framasoft.org/ping/7918b17b-a745-4db1-8575-9d2e07c97f79",
"update_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79",
"pause_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause",
"resume_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume",
"channels": "",
"timeout": 3600
}
POST https://hc.framasoft.org/api/v3/checks/<uuid>
Updates an existing check. All request parameters are optional. If you omit any parameter, Framasoft cron’s health checks will leave its value unchanged.
string, optional.
Name for the check.
Changed in API v3: the check's slug is no longer automatically generated
from the check's name. Instead, the client can specify the slug explicitly
via the slug field.
string, optional
Slug for the new check. The slug should only contain the following
characters: a-z, 0-9, hyphens, underscores. Example:
{"slug": "my-custom-slug"}
string, optional.
A space-delimited list of tags for the check.
Example:
{"tags": "reports staging"}
string, optional.
Description of the check.
number, optional.
The expected period of this check in seconds.
Minimum: 60 (one minute), maximum: 31536000 (365 days).
Example for a 5-minute timeout:
{"timeout": 300}
number, optional.
The grace period for this check in seconds.
Minimum: 60 (one minute), maximum: 31536000 (365 days).
string, optional.
A cron or systemd OnCalendar expression defining this check's schedule. Framasoft cron’s health checks will detect the expression type (cron or OnCalendar) automatically.
The schedule parameter takes precedence over the timeout field: If you specify
both the timeout and the schedule parameters, Framasoft cron’s health checks will save the
schedule and ignore the timeout.
Example using a cron expression ("run every half-hour"):
{"schedule": "0,30 * * * *"}
Example using an OnCalendar expression ("run at 12:00 of the last day of every month"):
{"schedule": "*-*~1 12:00"}
string, optional.
Server's timezone. This setting only has an effect in combination with the "schedule" parameter.
Example:
{"tz": "Europe/Riga"}
boolean, optional, default value: false.
Controls whether a paused ping automatically resumes when pinged (the default), or not. If set to false, a paused check will leave the paused state when it receives a ping. If set to true, a paused check will ignore pings and stay paused until you manually resume it from the web dashboard.
string, optional, default value: "".
Specifies the allowed HTTP methods for making ping requests. Must be one of the two values: "" (an empty string) or "POST".
Set this field to "" (an empty string) to allow HEAD, GET, and POST requests.
Set this field to "POST" to allow only POST requests.
Example:
{"methods": "POST"}
string, optional.
Set this field to a special value "*" to automatically assign all existing integrations. Example:
{"channels": "*"}
Set this field to a special value "" (empty string) to automatically unassign all existing integrations. Example:
{"channels": ""}
To assign specific integrations, use a comma-separated list of integration UUIDs. You can look up integration UUIDs using the List Existing Integrations API call.
Example:
{"channels":
"4ec5a071-2d08-4baa-898a-eb4eb3cd6941,746a083e-f542-4554-be1a-707ce16d3acc"}
Alternatively, if you have named your integrations in Framasoft cron’s health checks dashboard, you can specify integrations by their names. For this to work, your integrations need non-empty and unique names, and they must not contain commas. The names must match exactly, whitespace is significant.
Example:
{"channels": "Email to Alice,SMS to Alice"}
string, optional, default value: "".
Specifies the keywords for classifying inbound email messages as "Start" signals. Separate multiple keywords using commas.
Use this field in combination with the filter_subject and filter_body fields.
Setting filter_subject to true enables filtering on the email subject line,
filter_body enables filtering on the entire email body. Framasoft cron’s health checks supports both
plain text and HTML email messages.
Example:
{"filter_subject": true, "start_kw": "STARTED"}
In this example, Framasoft cron’s health checks classifies the email as a start signal if the Subject line contains the word "STARTED".
string, optional, default value: "".
Specifies the keywords for classifying inbound email messages as "Success" signals. Separate multiple keywords using commas.
Use this field in combination with the filter_subject and filter_body fields.
Setting filter_subject to true enables filtering on the email subject line,
filter_body enables filtering on the entire email body. Framasoft cron’s health checks supports both
plain text and HTML email messages.
Example:
{"filter_subject": true, "success_kw": "SUCCESS,COMPLETED"}
In this example, the email counts as success if the Subject line contains either the word "SUCCESS" or the word "COMPLETED".
string, optional, default value: "".
Specifies the keywords for classifying inbound email messages as "Failure" signals. Separate multiple keywords using commas.
Use this field in combination with the filter_subject and filter_body fields.
Setting filter_subject to true enables filtering on the email subject line,
filter_body enables filtering on the entire email body. Framasoft cron’s health checks supports both
plain text and HTML email messages.
Example:
{"filter_subject": true, "failure_kw": "FAILED, ERROR"}
In this example, the email counts as failure if the Subject line contains either the word "FAILED" or the word "ERROR".
boolean, optional, default value: false.
Enables filtering of inbound email messages by looking for keywords in their
subject lines. See also the success_kw and failure_kw fields.
boolean, optional, default value: false.
Enables filtering of inbound email messages by looking for keywords in their
message body. See also the success_kw and failure_kw fields.
string, optional, default value: "".
Deprecated. Use the success_kw, filter_subject and filter_body fields
instead.
Specifies the keywords for classifying inbound email messages as "Success" signals. Separate multiple keywords using commas. If any of the keywords is found in an email message's Subject line, the email message will count as "Success".
Set this field to "" (an empty string) to consider all inbound email messages as
"Success" (unless they match any keywords listed in subject_fail and are thus
classified as "Failure").
Example:
SUCCESS,COMPLETED
In this example, the email counts as success if the Subject line contains either the word "SUCCESS" or the word "COMPLETED".
string, optional, default value: "".
Deprecated. Use the failure_kw, filter_subject and filter_body fields
instead.
Specifies the keywords for classifying inbound email messages as "Failure" signals. Separate multiple keywords using commas. If any of the keywords is found in an email message's Subject line, the email message will count as "Failure".
Set this field to "" (an empty string) to perform no "Failure" classification.
Example:
FAILED,ERROR
In this example, the email counts as failure if the Subject line contains either the word "FAILED" or the word "ERROR".
curl https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79 \
--header "X-Api-Key: your-api-key" \
--data '{"name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
Or, alternatively:
curl https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79 \
--data '{"api_key": "your-api-key", "name": "Backups", "tags": "prod www", "timeout": 3600, "grace": 60}'
{
"name": "Backups",
"slug": "",
"tags": "prod www",
"desc": "",
"grace": 60,
"n_pings": 0,
"status": "new",
"started": false,
"last_ping": null,
"next_ping": null,
"manual_resume": false,
"methods": "",
"subject": "",
"subject_fail": "",
"start_kw": "",
"success_kw": "",
"failure_kw": "",
"filter_subject": false,
"filter_body": false,
"uuid": "7918b17b-a745-4db1-8575-9d2e07c97f79",
"ping_url": "https://hc.framasoft.org/ping/7918b17b-a745-4db1-8575-9d2e07c97f79",
"update_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79",
"pause_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause",
"resume_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume",
"channels": "",
"timeout": 3600
}
POST https://hc.framasoft.org/api/v3/checks/<uuid>/pause
Disables monitoring for a check without removing it. The check goes into a "paused"
state. You can resume monitoring of the check by pinging it, or by running
the Resume API call (useful when check's manual_resume=True).
This API call has no request parameters.
curl https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause \
--request POST --header "X-Api-Key: your-api-key" --data ""
Note: the --data "" argument forces curl to send a Content-Length request header
even though the request body is empty. For HTTP POST requests, the Content-Length
header is sometimes required by some network proxies and web servers.
{
"name": "Backups",
"slug": "",
"tags": "prod www",
"desc": "",
"grace": 60,
"n_pings": 0,
"status": "paused",
"started": false,
"last_ping": null,
"next_ping": null,
"manual_resume": false,
"methods": "",
"subject": "",
"subject_fail": "",
"start_kw": "",
"success_kw": "",
"failure_kw": "",
"filter_subject": false,
"filter_body": false,
"uuid": "7918b17b-a745-4db1-8575-9d2e07c97f79",
"ping_url": "https://hc.framasoft.org/ping/7918b17b-a745-4db1-8575-9d2e07c97f79",
"update_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79",
"pause_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause",
"resume_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume",
"channels": "",
"timeout": 3600
}
POST https://hc.framasoft.org/api/v3/checks/<uuid>/resume
Resumes a check. The check goes into the "new" state. Use this API call to resume
the monitoring of checks that are in the paused state, and have the manual_resume
configuration parameter set to True.
This API call has no request parameters.
curl https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume \
--request POST --header "X-Api-Key: your-api-key" --data ""
Note: the --data "" argument forces curl to send a Content-Length request header
even though the request body is empty. For HTTP POST requests, the Content-Length
header is sometimes required by some network proxies and web servers.
{
"name": "Backups",
"slug": "",
"tags": "prod www",
"desc": "",
"grace": 60,
"n_pings": 0,
"status": "new",
"started": false,
"last_ping": null,
"next_ping": null,
"manual_resume": false,
"methods": "",
"subject": "",
"subject_fail": "",
"start_kw": "",
"success_kw": "",
"failure_kw": "",
"filter_subject": false,
"filter_body": false,
"uuid": "7918b17b-a745-4db1-8575-9d2e07c97f79",
"ping_url": "https://hc.framasoft.org/ping/7918b17b-a745-4db1-8575-9d2e07c97f79",
"update_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79",
"pause_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause",
"resume_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume",
"channels": "",
"timeout": 3600
}
DELETE https://hc.framasoft.org/api/v3/checks/<uuid>
Permanently deletes the check from the user's account. Returns JSON representation of the check that was just deleted.
This API call has no request parameters.
curl https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79 \
--request DELETE --header "X-Api-Key: your-api-key"
{
"name": "Backups",
"slug": "",
"tags": "prod www",
"desc": "",
"grace": 60,
"n_pings": 0,
"status": "new",
"started": false,
"last_ping": null,
"next_ping": null,
"manual_resume": false,
"methods": "",
"subject": "",
"subject_fail": "",
"start_kw": "",
"success_kw": "",
"failure_kw": "",
"filter_subject": false,
"filter_body": false,
"uuid": "7918b17b-a745-4db1-8575-9d2e07c97f79",
"ping_url": "https://hc.framasoft.org/ping/7918b17b-a745-4db1-8575-9d2e07c97f79",
"update_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79",
"pause_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/pause",
"resume_url": "https://hc.framasoft.org/api/v3/checks/7918b17b-a745-4db1-8575-9d2e07c97f79/resume",
"channels": "",
"timeout": 3600
}
GET https://hc.framasoft.org/api/v3/checks/<uuid>/pings/
Returns a list of pings this check has received.
This endpoint returns pings in reverse order (most recent first), and the total number of returned pings depends on the account's billing plan: 100 for free accounts, 1000 for paid accounts.
curl https://hc.framasoft.org/api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/ \
--header "X-Api-Key: your-api-key"
{
"pings": [
{
"type": "success",
"date": "2020-06-09T14:51:06.113073+00:00",
"n": 4,
"scheme": "http",
"remote_addr": "192.0.2.0",
"method": "GET",
"ua": "curl/7.68.0",
"rid": "123e4567-e89b-12d3-a456-426614174000",
"duration": 2.896736,
"body_url": null
},
{
"type": "start",
"date": "2020-06-09T14:51:03.216337+00:00",
"n": 3,
"scheme": "http",
"remote_addr": "192.0.2.0",
"method": "GET",
"ua": "curl/7.68.0",
"rid": "123e4567-e89b-12d3-a456-426614174000",
"body_url": null
},
{
"type": "success",
"date": "2020-06-09T14:50:59.633577+00:00",
"n": 2,
"scheme": "http",
"remote_addr": "192.0.2.0",
"method": "GET",
"ua": "curl/7.68.0",
"rid": null,
"duration": 2.997976,
"body_url": null
},
{
"type": "start",
"date": "2020-06-09T14:50:56.635601+00:00",
"n": 1,
"scheme": "http",
"remote_addr": "192.0.2.0",
"method": "GET",
"ua": "curl/7.68.0",
"rid": null,
"body_url": null
}
]
}
GET https://hc.framasoft.org/api/v3/checks/<uuid>/pings/<n>/body
Returns a ping's logged body. The response always has the Content-Type: text/plain
response header and the ping body is returned verbatim in the response body.
curl https://hc.framasoft.org/api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/pings/397/body \
--header "X-Api-Key: your-api-key"
GET https://hc.framasoft.org/api/v3/checks/<uuid>/flips/
GET https://hc.framasoft.org/api/v3/checks/<unique_key>/flips/
Returns a list of "flips" this check has experienced. A flip is a change of status (from "down" to "up," or from "up" to "down").
This API endpoint supports time filtering via the seconds, start, and end query
parameters. If no time filters are specified, the API returns all stored
flips for a given check.
Notes about flip retention: Framasoft cron’s health checks stores historic flips for the current month and for two full months prior to the current month. The cleanup of older flips is a manual administrative action. Therefore, Framasoft cron’s health checks may return even older flips if the server administrator does not perform regular database cleanups.
Returns the flips from the last value seconds
Example:
https://hc.framasoft.org/api/v3/checks/<uuid|unique_key>/flips/?seconds=3600
Returns flips that are newer than the specified UNIX timestamp.
Example:
https://hc.framasoft.org/api/v3/checks/<uuid|unique_key>/flips/?start=1592214380
Returns flips that are older than the specified UNIX timestamp.
Example:
https://hc.framasoft.org/api/v3/checks/<uuid|unique_key>/flips/?end=1592217980
curl https://hc.framasoft.org/api/v3/checks/f618072a-7bde-4eee-af63-71a77c5723bc/flips/ \
--header "X-Api-Key: your-api-key"
[
{
"timestamp": "2020-03-23T10:18:23+00:00",
"up": 1
},
{
"timestamp": "2020-03-23T10:17:15+00:00",
"up": 0
},
{
"timestamp": "2020-03-23T10:16:18+00:00",
"up": 1
}
]
GET https://hc.framasoft.org/api/v3/channels/
Returns a list of integrations belonging to the project.
curl --header "X-Api-Key: your-api-key" https://hc.framasoft.org/api/v3/channels/
{
"channels": [
{
"id": "4ec5a071-2d08-4baa-898a-eb4eb3cd6941",
"name": "My Work Email",
"kind": "email"
},
{
"id": "746a083e-f542-4554-be1a-707ce16d3acc",
"name": "My Phone",
"kind": "sms"
}
]
}
GET https://hc.framasoft.org/api/v3/badges/
Returns a map of all tags in the project, with badge URLs for each tag. Framasoft cron’s health checks provides badges in a few different formats:
svg: returns the badge as an SVG document.json: returns a JSON document which you can use to generate a custom badge
yourself.shields: returns JSON in a Shields.io compatible format.In addition, badges have 2-state and 3-state variations:
svg, json, shields: reports two states: "up" and "down". It
considers any checks in the grace period as still "up".svg3, json3, shields3: reports three states: "up", "late", and "down".The response includes a special * entry: this pseudo-tag reports the overall status
of all checks in the project.
curl --header "X-Api-Key: your-api-key" https://hc.framasoft.org/api/v3/badges/
{
"badges": {
"backup": {
"svg": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M-2/backup.svg",
"svg3": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M/backup.svg",
"json": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M-2/backup.json",
"json3": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M/backup.json",
"shields": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M-2/backup.shields",
"shields3": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/LOegDs5M/backup.shields"
},
"db": {
"svg": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm-2/db.svg",
"svg3": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm/db.svg",
"json": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm-2/db.json",
"json3": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm/db.json",
"shields": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm-2/db.shields",
"shields3": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/99MuQaKm/db.shields"
},
"prod": {
"svg": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8-2/prod.svg",
"svg3": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8/prod.svg",
"json": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8-2/prod.json",
"json3": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8/prod.json",
"shields": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8-2/prod.shields",
"shields3": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/1TEhqie8/prod.shields"
},
"*": {
"svg": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe-2.svg",
"svg3": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe.svg",
"json": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe-2.json",
"json3": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe.json",
"shields": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe-2.shields",
"shields3": "https://hc.framasoft.org/badge/67541b37-8b9c-4d17-b952-690eae/9X7kcZoe.shields"
}
}
}
GET https://hc.framasoft.org/api/v3/status/
Runs a test query and returns HTTP 200 if the query completes successfully. Use this endpoint to monitor the uptime of your Healthchecks instance with an external uptime monitoring system.