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

  1. Log in and open Profile > API keys. Your email address has to be verified.
  2. Make a key. Copy it straight away: it's shown once. It starts with sou_.
  3. 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:

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.

FreePlus
API keys 110
Calls an hour (per key) 601,000
Resets or new dates per counter a day 1100
Counters created a day 050
Create, change and delete counters NoYes
Webhooks 05
Milestone and reminder emails NoYes

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/meYour account, plan, limits, use, and this key.
GET/countersYour 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}/resetReset 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}/resetsReset history, current and best streak.
POST/countersMake a counter (Plus).
DELETE/counters/{counter}Delete a counter (Plus).
GET/stylesThe sign styles and animations. No key needed.
GET/openapi.jsonThis 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
}

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"]}'
FieldMeaning
titleNeeded. At most 30 characters; the sign reads DAYS SINCE / DAYS UNTIL and the title.
modesince (default) or until.
startSince: when it started, not in the future (default now). Until: the date, in the future (needed).
timezoneAn 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, animationSlugs from GET /styles.
privacyprivate (default), public or shared; password sets a shared counter's password.
slugThe end of its link: letters, numbers, - and _. Empty removes it.
tagsA list of words; replaces the counter's tags.
expiresA 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." }
  }
}
StatuscodeMeaning
400bad_json, bad_filter, bad_cursor, empty_bodyThe request couldn't be read.
401missing_key, invalid_key, expired_keyNo key, a wrong or revoked one, or one past its expiry.
403missing_scope, plan_required, counter_key, not_availableThe key or the plan doesn't allow it, or the account can't use the API (email not verified).
404counter_not_found, not_foundNone of your counters (or none this key may see) has that id or slug; or no such endpoint.
405method_not_allowedWrong method; Allow lists the right ones.
409until_counterA reset of an Until counter: give it a new date instead.
422invalid, idempotency_mismatchFields to fix (in fields), or an Idempotency-Key used for a different request.
429rate_limited, daily_limit, too_many_failuresOver a limit: wait Retry-After seconds. 20 calls with a wrong key in 15 minutes block that address for 15 minutes.
503api_off, creation_offSwitched 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.

EventWhendata
counter.resetA Since counter is reset (button, API or tip)previous_start, streak_days, source
counter.milestoneA Since counter reaches 7, 30, 50, 100, 200, 365 or 500 days, then every year and every 1,000 daysdays, label
counter.reminderAn Until counter is 30, 7 or 1 day from its datedays_left
counter.until_reachedAn Until counter reaches its date and becomes a Since counterdate
counter.testYou press Send a testnote
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"}}
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.

[![last incident](https://www.sinceoruntil.com/badge/last-incident.svg)](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.