Ping URLs

This page lists every ping URL FlatLyne accepts, what each one does to a check, and every response it can return. Ping URLs live at the root of https://api.flatlyne.com/, with no /ping prefix.

SummaryCopy Anchor Link

The token is the long random part of a check's ping URL. It's 43 characters of letters, digits, - and _. Find it in the dashboard: copy it from the Ping URL column of your checks list, or from Ping endpoint on the check's page.

Ping keys are covered on their own page: see Ping keys.

What every ping URL has in commonCopy Anchor Link

You can call every URL on this page with GET or POST. Other methods, such as PUT, get 405 Method Not Allowed.

Each ping that FlatLyne accepts is stored with:

• Its kind: success, start or fail.
• The exit code, if the URL included one.
• The source address of the request.
• The User-Agent header.
• The request body, up to 10 KB (10,240 bytes). If you send more, FlatLyne keeps the first 10 KB and still accepts the ping.

To see these details, open the check's page and select a ping in its history. The dialog shows Time received, Source, Duration, User agent and Body. FlatLyne keeps the newest 100 pings for each check and deletes older ones.

ResponsesCopy Anchor Link

Every response body is plain text, not JSON.

A 404 looks the same whether a token never existed, was revoked or expired. That way, someone guessing URLs learns nothing about which tokens are or were real.

Only a 200 means FlatLyne recorded the ping. A 400, 403, 404 or 429 response doesn't store anything or change the check.

Rate limitCopy Anchor Link

Each check accepts up to 3 pings per minute. Every kind of ping counts: success, start, fail and exit-code pings all share the same limit, whether they arrive through the check's token or a ping key. FlatLyne answers a 4th ping inside that minute with 429 and doesn't record it.

The limit applies to each check separately, so one busy check never slows down another. A job that sends a start ping and a success ping on every run uses 2 of its 3 pings per minute.

Success: /tokenCopy Anchor Link

Send a success ping when your job finishes without errors.

• Methods: GET, POST
• Path: /<token>

FlatLyne records a success ping, moves the check to Up and sets the next due time. For a simple schedule, that's the time of the ping plus the period. For a cron schedule, it's the next time the cron expression matches in the check's timezone. If the check was Down, FlatLyne sends a recovery alert.

A success ping also ends a manual pause: a Paused check moves to Up. A check paused by a plan change is different: every ping to it gets 403 until you activate it in the dashboard.

curl -fsS -m 10 --retry 5 \
  https://api.flatlyne.com/CSps9LOZGccsl2o7ieL0_YrQyZJtkGK_0H1u30FJ-NI

Start: /token/startCopy Anchor Link

Send a start ping when your job begins.

• Methods: GET, POST
• Path: /<token>/start

FlatLyne records a start ping (shown as STARTED in the check's history) and leaves the check's state and due time as they are. A job that starts and then hangs still goes late and down on schedule. See Start pings.

curl -fsS -m 10 --retry 5 \
  https://api.flatlyne.com/CSps9LOZGccsl2o7ieL0_YrQyZJtkGK_0H1u30FJ-NI/start

Fail: /token/failCopy Anchor Link

Send a fail ping when your job knows it failed.

• Methods: GET, POST
• Path: /<token>/fail

FlatLyne records a fail ping, moves the check to Down right away and sends an alert. It doesn't wait for the grace period. The due time stays as it was. Only a later success ping moves the check back to Up.

curl -fsS -m 10 --retry 5 \
  https://api.flatlyne.com/CSps9LOZGccsl2o7ieL0_YrQyZJtkGK_0H1u30FJ-NI/fail

Exit code: /token/exit-codeCopy Anchor Link

Send your job's exit code and let FlatLyne decide whether the run succeeded.

• Methods: GET, POST
• Path: /<token>/<exit-code>

The exit code must be a whole number. 0 counts as a success ping and every other number counts as a fail ping. FlatLyne stores the code with the ping. If the last segment isn't a number, FlatLyne returns 400 invalid exit code and records nothing.

/usr/local/bin/backup-db-nightly.sh; \
  curl -fsS -m 10 --retry 5 \
  https://api.flatlyne.com/CSps9LOZGccsl2o7ieL0_YrQyZJtkGK_0H1u30FJ-NI/$?

Failures, exit codes and start pings has shell patterns for sending the right code.

Ping key URLsCopy Anchor Link

A project ping key lets you ping a check by its slug instead of its token. Every form above has a ping key version:

If no check in the project has that slug, FlatLyne returns 404 and records nothing.

curl -fsS -m 10 --retry 5 \
  https://api.flatlyne.com/RudYgUFqrxce2CdpAHz3csYP83ml_HKdSoBwxeezF_o/backup-db-nightly

See Ping keys for slug rules and how to create a key.

Keeping a ping URL privateCopy Anchor Link

Each check gets one ping URL when you create it. The URL doesn't expire, so keep it out of public repositories and logs. Store it like any other secret, for example in an environment variable your job reads.

curl -fsS -m 10 --retry 5 "$BACKUP_DB_PING_URL"

If a URL leaks, select Regenerate URL on the check's page. This is a Pro and Business feature. The old URL stops working immediately and gets 404, so update your job to the new one right away. On Free, upgrade, or delete the check and create it again, which loses its ping history. You can also use a ping key, which you can revoke and replace on any plan that includes them.

What's nextCopy Anchor Link

• Report failures and exit codes
• Ping checks by name with a ping key
• Copy a ready-made snippet
• Make your pings survive network errors