← Other blogs

Push notification curl example: five recipes and six quoting traps

Copy-paste commands for plain text, JSON with Markdown, Idempotency-Key retries and avoiding 400 invalid_body errors.

· 3 min read

A push notification curl example takes thirty seconds to copy and paste, yet half of first attempts fail over shell quoting or a field limit. Use the working commands below to test plain text, Markdown JSON, safe retries and shell variables without guessing what caused a 400 error.

Step 1: export your token safely

Create a token inside the AyePing app on the Tokens page and export it in your terminal instead of hardcoding it into shell history or scripts:

export AYEPING_TOKEN="paste-your-token-here"

Because a token can only send pings to its own owner, keeping it in an environment variable limits exposure and lets you pause a single machine later without changing any other host.

Step 2: send a one-line plain-text ping

Any body that does not open with { is read as the title. That makes a basic check three lines:

curl https://ayeping.com/@you \
  -H "Authorization: Bearer $AYEPING_TOKEN" \
  -d "Build 42 passed"

AyePing replies with HTTP 202 and a JSON id, plus RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers.

Step 3: send JSON with Markdown and a chip

Wrap the body in single quotes and start with { when you want a formatted body and a colored tag:

curl https://ayeping.com/@you \
  -H "Authorization: Bearer $AYEPING_TOKEN" \
  -d '{"title":"Deploy complete","message":"Released **v2.4.1** to staging.\n- 0 errors","label":{"text":"staging","color":"blue"}}'

You do not need -H "Content-Type: application/json" with curl -d when { is the first character, though adding it causes no harm.

Common curl pitfalls and exact rules

Symptom Status and error What broke
Title cut off or rejected 400 invalid_body title must be 1 to 100 chars on one line
Color ignored or rejected 400 invalid_body Use gray, red, orange, yellow, green, teal, blue, purple, pink
Missing JSON formatting 202 with raw braces Leading space before { made AyePing read it as plain text
Giant log file pasted 413 body_too_large Whole request body cannot exceed 32 KB
Leading @ rejected by tool Client error before send Switch endpoint to https://ayeping.com/ping/@username
Double quote expansion error Broken JSON in Bash Keep single quotes outside JSON or build it with jq

Step 4: prevent duplicate notifications on retries

If a cron wrapper or CI job retries timed-out requests, attach an Idempotency-Key header (up to 255 characters):

curl https://ayeping.com/@you \
  -H "Authorization: Bearer $AYEPING_TOKEN" \
  -H "Idempotency-Key: nightly-sync-2026-11-20" \
  -d '{"title":"Nightly sync failed","label":{"text":"sync","color":"red"}}'

A repeated request using the same key and token gives back the first ping's id, skips sending a second buzz and does not subtract another ping from your allowance. Keep the key deterministic per run (such as the job name plus date or build number) and under 255 characters.

Step 5: watch quota, failure paths and hourly ceilings

Every token enforces an hourly limit between 1 and 3,600 requests (60 by default), returning 429 (rate_limited) with a Retry-After count if crossed. Too many bad tokens from one IP address also trigger a 429 (too_many_failed_attempts), asking you to wait a minute before retrying. If a token was paused in the app, the endpoint answers with 403 (token_paused) until you resume it on the Tokens page.

As of November 2026, AyePing's Free plan grants 5 pings to try and 3 tokens without a card (90-day retention). Hobby is $8 monthly or $49 yearly (120,000 pings, 25 tokens) and Pro is $20 monthly or $120 yearly (1,200,000 pings, 100 tokens), both keeping pings for a year with no carryover. If you exhaust an allowance, the endpoint returns 402 (quota_exhausted) and sends at most one push a day to notify you.

FAQ

Why did AyePing show my entire JSON object as the title?

If there is a space or newline before {, AyePing does not treat the body as JSON and uses the whole raw string as the title instead.

Links work in Markdown and prompt before opening. Images are not loaded (only alt text displays), so senders cannot embed tracking pixels.

What happens if I send the wrong username with a valid token?

AyePing returns HTTP 401 with {"error": "unauthorized"} because the token belongs to a different account.