API docs

Quickstart

You need a tinyping account and about two minutes.

1. Create a project
   A project is one app or service that sends alerts. Create one from your dashboard.
2. Copy the token
   Create a token on the project page and copy it right away, because it is shown only once. Use it in place of tp_YOUR_TOKEN below, and use the project id from the page in place of YOUR_PROJECT_ID.
3. Send your first event
   Run one of the examples below. The event lands in your inbox and arrives as a push notification on every device with alerts turned on.

curl -X POST https://tinyping.app/api/v1/projects/YOUR_PROJECT_ID/events \
  -H 'Authorization: Bearer tp_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"title":"New sign-up","body":"ada@example.com started a trial","kind":"signup","priority":"normal"}'

A 201 response with an id means the event was stored.

Authentication

Every request carries a project token in the Authorization header.

Authorization: Bearer tp_YOUR_TOKEN

• A token belongs to one project and can only send events to it. Using it on another project returns 403.
• Tokens are shown once when you create them and are stored only as a hash. If you lose one, create a new one.
• Keep tokens on your server or in your CI secrets. Never put one in a browser bundle or a mobile app, because anyone who has it can send alerts to your project.
• To rotate a token, create a new one on the project page, deploy it, then revoke the old one. A revoked token stops working immediately.

Send an event

Send a POST request with a JSON body to your project's events endpoint.

Surrounding whitespace is trimmed. The whole request body can be up to 16,384 bytes.

Example request

curl -X POST https://tinyping.app/api/v1/projects/YOUR_PROJECT_ID/events \
  -H 'Authorization: Bearer tp_YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"title":"New sign-up","body":"ada@example.com started a trial","kind":"signup","priority":"normal"}'

Example response

A successful call returns status 201 with the id and creation time of the stored event.

{
  "id": "0b6f2c1e-3d4a-4f5b-9a7c-1e2d3c4b5a69",
  "createdAt": "2026-11-11T09:30:00.000Z"
}

Errors

Failed requests return a JSON body with a readable error and a stable code. Branch on the code, not on the message.

{
  "error": "title: Too small: expected string to have >=1 characters",
  "code": "validation_failed",
  "issues": [
    {
      "path": "title",
      "message": "Too small: expected string to have >=1 characters"
    }
  ]
}

Limits

• Each token can send up to 60 events every 60 seconds. Past that, requests fail with 429 and rate_limited.
• A request body can be up to 16,384 bytes.
• Monthly events are counted for the whole workspace across all its projects, and the count starts over at the beginning of each month in UTC. When it is used up, requests fail with 429 and monthly_limit_reached until the reset.
• Events older than your plan's history are deleted.

Getting alerts on your phone

Install tinyping as an app, then turn on notifications for it.

iPhone and iPad

1. Use iOS 16.4 or later. Older versions cannot receive these alerts.
2. Open tinyping in Safari, tap Share, then tap Add to Home Screen.
3. Open tinyping from its Home Screen icon, not from Safari, and sign in.
4. Turn on notifications in the app when it asks, or from its notification settings.

Android

1. Open tinyping in Chrome and choose Install app from the menu. You can also keep using it in the browser.
2. Allow notifications when Chrome asks, or turn them on in the app's notification settings.

Desktop Chrome

1. Open tinyping and click the install icon in the address bar. You can also keep using it in a tab.
2. Allow notifications when Chrome asks, or turn them on in the app's notification settings.

If alerts do not show up, check that notifications are allowed for tinyping in your device settings.

Recipes

Copy an example, set the TINYPING_TOKEN environment variable and replace the project id in the URL.

async function notifySignup(user) {
  await fetch('https://tinyping.app/api/v1/projects/YOUR_PROJECT_ID/events', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TINYPING_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title: 'New sign-up',
      body: user.email,
      kind: 'signup',
    }),
  }).catch(() => {});
}

./backup.sh || curl -X POST https://tinyping.app/api/v1/projects/YOUR_PROJECT_ID/events \
  -H "Authorization: Bearer $TINYPING_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Backup failed","body":"The nightly backup exited with an error","kind":"backup","priority":"high"}'

export async function POST(request) {
  const payment = await request.json();
  await fetch('https://tinyping.app/api/v1/projects/YOUR_PROJECT_ID/events', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.TINYPING_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title: `Payment of ${payment.amount} ${payment.currency}`,
      body: payment.customer_email,
      kind: 'payment',
    }),
  });
  return new Response('ok');
}