Docs/Developers

API

Create, update and read timers and counters from your own code, Zapier or your shop.

The Inboxclock API lets you manage timers and counters without opening the app. It uses JSON over HTTPS.

Authentication

Create a key in Account → API keys. The key is shown once, so store it safely. Send it with every request:

Authorization: Bearer ick_...

Each key may make up to 120 requests a minute. Keep keys on your server; never put them in a web page.

Timers

Method Path What it does
GET /v1/timers List your timers and counters
GET /v1/timers/{id} Get one
POST /v1/timers Create one
PATCH /v1/timers/{id} Change the name, settings, or archive it
DELETE /v1/timers/{id} Delete it
POST /v1/timers/{id}/counter Set or change a counter’s number

The base URL is https://inboxclock.com.

Create a timer

curl -X POST https://inboxclock.com/v1/timers \
  -H "Authorization: Bearer ick_..." -H "Content-Type: application/json" \
  -d '{"name": "Black Friday", "config": {"deadline": "2026-11-27T23:59:00-05:00", "timezone": "America/New_York"}}'

Leave out any setting to use the default (the Plain template). To create a counter, add "kind": "counter" and settings such as "counterValue": 50 and "counterText": "seats left".

Change settings

PATCH merges the settings you send into the existing ones:

curl -X PATCH https://inboxclock.com/v1/timers/TIMER-ID \
  -H "Authorization: Bearer ick_..." -H "Content-Type: application/json" \
  -d '{"config": {"deadline": "2026-11-30T23:59:00Z"}}'

Send "archived": true to archive a timer.

Update a counter

curl -X POST https://inboxclock.com/v1/timers/TIMER-ID/counter \
  -H "Authorization: Bearer ick_..." -H "Content-Type: application/json" \
  -d '{"increment": -1}'

Send {"value": 12} to set the number, or {"increment": n} to add to it. Use a negative number to subtract.

Responses

Successful responses wrap the item in data:

{
  "data": {
    "id": "8f3c…",
    "name": "Black Friday",
    "kind": "countdown",
    "archived": false,
    "image_url": "https://inboxclock.app/t/8f3c….gif",
    "embed_html": "<img src=\"https://inboxclock.app/t/8f3c….gif\" …>",
    "config": { "mode": "fixed", "deadline": "2026-11-28T04:59:00.000Z", … },
    "created_at": "…",
    "updated_at": "…"
  }
}

Errors return an HTTP status and a message:

{ "error": { "status": 400, "message": "Width must be between 300 and 800 pixels." } }
Status Meaning
400 The request or a setting is not valid. The message says which.
401 The key is missing or not valid.
403 The account cannot do this, for example it reached the 100-timer limit.
404 The timer does not exist or belongs to someone else.
429 Too many requests. Wait a minute.

Settings

The config object accepts the same settings as the editor. The most useful ones:

Setting Values
kind countdown or counter
mode fixed, evergreen or recurring
deadline ISO date and time, for fixed timers
timezone IANA name, such as Europe/London
evergreenMinutes Length per reader, for evergreen timers
recurDays, recurTime Weekdays (0 is Sunday) and HH:MM, for recurring timers
headline Text above the timer, up to 60 characters
background, foreground, accent, labelColor Six-digit hex colors
expiry, expiryMessage message, zeros or hide, and the message text
link, expiredLink Click-through links
urgentHours, urgentColor, urgentHeadline The last-hours look. urgentHours is 0, 1, 6, 12, 24 or 48.
counterValue, counterGoal, counterText, counterPrefix Counter settings

The full set is returned by GET /v1/timers/{id}. Copy it as a starting point.