API
Work with your counters from other apps: reset one when a smart-home sensor fires or a monitoring alert goes off, show them on a dashboard, or make and change them from a script. Everything is JSON over HTTPS with an API key.
Getting started
- Log in and open Profile > API keys. Your email address has to be verified.
- Make a key. Copy it straight away: it's shown once. It starts with
sou_. - Send it with every call:
curl https://www.sinceoruntil.com/api/v1/me \ -H "Authorization: Bearer YOUR_KEY"
The address is https://www.sinceoruntil.com/api/v1 for every counter, Since or Until
(www.untilorsince.com works too). If your app can't set an Authorization header, send
X-API-Key: YOUR_KEY instead. Never put a key in the address: addresses end up in logs.
Keys
When you make a key you choose:
- What it can do. Read your counters; read and reset, which also resets a Since counter or gives an Until counter a new date; or everything, which also makes, changes and deletes counters (Plus plan).
- Which counters. All of yours, or just one. A key for one counter can only read and reset that counter, so if it leaks, that's the worst anyone can do with it. It's the right kind for a device.
- When it expires: never, or in 30 days, 90 days or a year.
Revoke a key on the same page and calls with it stop at once. The page also shows when and from where each key was last used, and your recent calls.
Plans and limits
The API is part of the Plus plan. Plus has higher limits and can make, change and delete counters. Ask about Plus.
| Free | Plus | |
|---|---|---|
| API keys | 1 | 10 |
| Calls an hour (per key) | 60 | 1,000 |
| Resets or new dates per counter a day | 1 | 100 |
| Counters created a day | 0 | 50 |
| Create, change and delete counters | No | Yes |
| Webhooks | 0 | 5 |
| Milestone and reminder emails | No | Yes |
Resets and new dates count per counter over any 24 hours; the Reset button on your dashboard isn't limited. Every answer carries
X-RateLimit-Limit and X-RateLimit-Remaining for the hourly limit, and a
429 answer has Retry-After (seconds). GET /me shows your plan,
limits and use.
Endpoints
{counter} is the counter's id (never changes) or its slug, the end of its link.
| GET | /me | Your account, plan, limits, use, and this key. |
| GET | /counters | Your counters, newest first. Filters: mode, privacy, tag; pages: limit (up to 100) and cursor. |
| GET | /counters/{counter} | One counter, with its reset count and best streak. |
| POST | /counters/{counter}/reset | Reset a Since counter to now, or to at. |
| PATCH | /counters/{counter} | Change a counter. With a read-and-reset key: only start, to give an Until counter a new date. |
| GET | /counters/{counter}/resets | Reset history, current and best streak. |
| POST | /counters | Make a counter (Plus). |
| DELETE | /counters/{counter} | Delete a counter (Plus). |
| GET | /styles | The sign styles and animations. No key needed. |
| GET | /openapi.json | This API as an OpenAPI 3.1 spec. No key needed. |
The counter
{
"id": "5f0c1c2e-8a4b-4c1e-9d55-0f2a7c1b9e11",
"slug": "last-incident",
"url": "https://www.sinceoruntil.com/view/last-incident",
"title": "last incident",
"mode": "since",
"start": "2026-11-14T08:30:00-06:00",
"timezone": "America/Chicago",
"days": 1,
"style": "white",
"animation": "standard",
"privacy": "public",
"has_password": false,
"tags": ["work"],
"expires_at": null,
"hidden": false,
"converted_at": null,
"created_at": "2026-10-01T14:02:11Z",
"resets": 3,
"best_streak": 45
}
startis when a Since counter started, or the date an Until counter counts down to, with the counter's offset.daysis the whole days since it, or until it.- When an Until counter reaches its date it becomes a Since counter:
modeturns tosinceandconverted_atsays when. hiddenis true when an admin has hidden it or it's pastexpires_at; an expired counter is deleted 30 days later.resetsandbest_streakcome with one counter, not in lists.- Times in requests are ISO 8601:
2026-11-14,2026-11-14T08:30:00or2026-11-14T08:30:00-06:00. Without an offset they're read in the counter's time zone.
Reset a counter, or give it a new date
A Since counter resets to now, or to an earlier moment with at:
curl -X POST https://www.sinceoruntil.com/api/v1/counters/last-incident/reset \
-H "Authorization: Bearer YOUR_KEY"
curl -X POST https://www.sinceoruntil.com/api/v1/counters/last-incident/reset \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"at": "2026-11-14T08:30:00-06:00"}'
The answer is the counter with its new start. Each reset is added to the counter's history, which shows its best streak.
An Until counter isn't reset: give it a new date, which must be in the future. Handy for a countdown that repeats, like the next payday:
curl -X PATCH https://www.sinceoruntil.com/api/v1/counters/payday \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"start": "2026-12-31"}'
Apps that can only send form fields can send at=… or start=… as a form body instead of JSON.
Make and change counters (Plus)
curl -X POST https://www.sinceoruntil.com/api/v1/counters \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <any unique text>" \
-d '{"title": "the last outage", "mode": "since", "start": "2026-11-02T14:00:00",
"timezone": "America/Chicago", "privacy": "public", "tags": ["work"]}'
| Field | Meaning |
|---|---|
| title | Needed. At most 30 characters; the sign reads DAYS SINCE / DAYS UNTIL and the title. |
| mode | since (default) or until. |
| start | Since: when it started, not in the future (default now). Until: the date, in the future (needed). |
| timezone | An IANA zone like America/Chicago. A new counter without it uses your account's time zone (on your profile, and in GET /me), else UTC. Changing it keeps the same moment. |
| style, animation | Slugs from GET /styles. |
| privacy | private (default), public or shared; password sets a shared counter's password. |
| slug | The end of its link: letters, numbers, - and _. Empty removes it. |
| tags | A list of words; replaces the counter's tags. |
| expires | A date, YYYY-MM-DD: hidden after that day, deleted 30 days later. Empty or null removes it. |
PATCH /counters/{counter} takes the same fields; send only what changes.
DELETE /counters/{counter} deletes it for good.
Idempotency-Key
A POST can send an Idempotency-Key header with any unique string. If the call times out and
you send it again with the same key, you get the first answer back (with Idempotent-Replayed: true) instead of a second
counter or a second reset. Keys are kept 24 hours; using one for a different request is an error.
Errors
An error has a status and a JSON body with a code to check and a message to show:
HTTP 422
{
"error": {
"code": "invalid",
"message": "Some fields need fixing.",
"fields": { "start": "A Since counter can't start in the future." }
}
}
| Status | code | Meaning |
|---|---|---|
| 400 | bad_json, bad_filter, bad_cursor, empty_body | The request couldn't be read. |
| 401 | missing_key, invalid_key, expired_key | No key, a wrong or revoked one, or one past its expiry. |
| 403 | missing_scope, plan_required, counter_key, not_available | The key or the plan doesn't allow it, or the account can't use the API (email not verified). |
| 404 | counter_not_found, not_found | None of your counters (or none this key may see) has that id or slug; or no such endpoint. |
| 405 | method_not_allowed | Wrong method; Allow lists the right ones. |
| 409 | until_counter | A reset of an Until counter: give it a new date instead. |
| 422 | invalid, idempotency_mismatch | Fields to fix (in fields), or an Idempotency-Key used for a different request. |
| 429 | rate_limited, daily_limit, too_many_failures | Over a limit: wait Retry-After seconds. 20 calls with a wrong key in 15 minutes block that address for 15 minutes. |
| 503 | api_off, creation_off | Switched off on the site for now. |
Every answer has an X-Request-Id; quote it if you ask us about a call.
Examples
Home Assistant
In configuration.yaml, with the key in secrets.yaml; then call rest_command.reset_counter from any automation:
rest_command:
reset_counter:
url: "https://www.sinceoruntil.com/api/v1/counters/last-incident/reset"
method: POST
headers:
Authorization: !secret counter_key # "Bearer YOUR_KEY"
Hubitat, IFTTT and other apps
Most can set one header: use X-API-Key.
POST https://www.sinceoruntil.com/api/v1/counters/last-incident/reset X-API-Key: YOUR_KEY
Python
import requests
API = "https://www.sinceoruntil.com/api/v1"
H = {"Authorization": "Bearer YOUR_KEY"}
for c in requests.get(f"{API}/counters", headers=H, timeout=10).json()["data"]:
print(c["days"], c["mode"], c["title"])
r = requests.post(f"{API}/counters/last-incident/reset", headers=H, timeout=10)
print(r.status_code, r.json())
JavaScript
const r = await fetch("https://www.sinceoruntil.com/api/v1/counters/last-incident/reset", {
method: "POST",
headers: { Authorization: "Bearer YOUR_KEY" },
});
console.log(r.status, await r.json());
Call it from a server or script, not from a web page anyone can open: the key would be visible in the page.
Webhooks (Plus)
Instead of asking for changes, let us tell you. Add a webhook on Profile > Webhooks: an https:// address, all your counters or one, and the events you want. We POST a JSON event to it within a few minutes of it happening.
| Event | When | data |
|---|---|---|
| counter.reset | A Since counter is reset (button, API or tip) | previous_start, streak_days, source |
| counter.milestone | A Since counter reaches 7, 30, 50, 100, 200, 365 or 500 days, then every year and every 1,000 days | days, label |
| counter.reminder | An Until counter is 30, 7 or 1 day from its date | days_left |
| counter.until_reached | An Until counter reaches its date and becomes a Since counter | date |
| counter.test | You press Send a test | note |
POST https://example.com/hooks/counters
Content-Type: application/json
X-Sou-Event: counter.milestone
X-Sou-Delivery: evt_…
X-Sou-Signature: t=1763251200,v1=<64 hex characters>
{"id": "evt_…", "type": "counter.milestone",
"created_at": "2026-11-16T00:00:00Z",
"counter": { …the counter, as in the API… },
"data": {"days": 100, "label": "100 days"}}
- Answer with any 2xx within 6 seconds. Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours; after 15 failures in a row the webhook is switched off (Send a test switches it back on).
- The same event can arrive twice (a retry after a slow answer): use
idto skip ones you've seen. - Check the signature so you know it came from us:
v1is the HMAC-SHA256 oft, a dot and the raw body, keyed with the webhook's signing secret (on Profile > Webhooks). Refuse it iftis more than 5 minutes old.
import hashlib, hmac, time
def verify(body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
expected = hmac.new(secret.encode(), parts["t"].encode() + b"." + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])
Badge image
Every public counter has a small live picture for a README, a status page or a website, at
/badge/{counter}.svg. No key needed; it updates every 10 minutes. The counter's edit page has the code to copy.
[](https://www.sinceoruntil.com/view/last-incident)
Options: ?style=flat-square for square corners, ?label=… for your own words on the left,
?color=7c3aed for the right half's colour. A counter that isn't public, or doesn't exist, shows a grey "not found".
Your data
Every call is logged with its time, key, the calling IP address, what was asked and the answer. You see the recent ones on Profile > API keys and all of them in your data download; they're deleted after 90 days, or with your account. See the privacy policy.
Questions or ideas for the API? Get in touch.