Countdown Timer API Documentation

Quick start

Create a timer, keep the timer ID it returns, then use that ID for every later call. Start in Sandbox — it is free with any account and behaves like Production.

1. Step 01

   Create an API key

   Open the developer dashboard and issue a Sandbox key. The secret is shown once.

2. Step 02

   Create a timer

   POST to /timers with a name, a type, and its timing field. Save the returned ID.

3. Step 03

   Read or automate it

   Poll the status endpoint when you render, or attach a webhook rule and be called instead.

curl -X POST https://countdownshare.com/api/v1/timers \
  -H "Authorization: Bearer $COUNTDOWNSHARE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-launch-2030" \
  -d '{
    "name": "Product launch",
    "type": "fixed",
    "deadline_at": "2030-01-01T14:00:00Z"
  }'

const response = await fetch(
  "https://countdownshare.com/api/v1/timers",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.COUNTDOWNSHARE_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "product-launch-2030",
    },
    body: JSON.stringify({
      name: "Product launch",
      type: "fixed",
      deadline_at: "2030-01-01T14:00:00Z",
    }),
  },
);

const { data, request_id } = await response.json();
if (!response.ok) throw new Error(`${data?.code} (${request_id})`);

console.log(data.id, data.remaining_seconds);

Countdown API authentication

Send your secret API key as a bearer token on every request. Keep it on your server: a key in frontend JavaScript, a mobile binary, or a public repository is a key anyone can use to create timers on your account.

Authorization: Bearer cs_live_a1b2c3d4_...
Content-Type: application/json

API keys

Sandbox and Production

Every account has both. They share the same code paths, so anything that works in Sandbox works in Production — but they never share data. The separation is enforced by database constraints, not only by application logic, so a Sandbox key cannot read a Production timer under any circumstances.

Timer types

Every type uses the same endpoints. The type you send at creation decides which timing field is required and is fixed for the life of the timer.

Endpoint reference

All paths are relative to https://countdownshare.com/api/v1 and return JSON. Webhook endpoints are listed under webhooks.

Create a countdown with the REST API

POST /timers requires an Idempotency-Key header. New timers are private drafts unless you send publish: true, which is Production only. Save the returned timer ID: every later call needs it.

curl -X POST https://countdownshare.com/api/v1/timers \
  -H "Authorization: Bearer $COUNTDOWNSHARE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: product-launch-2030" \
  -d '{
    "name": "Product launch",
    "type": "fixed",
    "deadline_at": "2030-01-01T14:00:00Z"
  }'

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Product launch",
    "type": "fixed",
    "status": "draft",
    "revision": 1,
    "deadline_at": "2030-01-01T14:00:00.000Z",
    "duration_seconds": null,
    "remaining_seconds": 2692800,
    "timezone": "UTC",
    "recurrence": null,
    "external_user_id": null,
    "expiry": { "behavior": "show_message" },
    "metadata": {},
    "outputs": null,
    "created_at": "2029-12-01T10:00:00.000Z",
    "updated_at": "2029-12-01T10:00:00.000Z"
  },
  "request_id": "7b82b7f7-4d13-497b-9f20-58d46fd7a510"
}

Retrieve remaining countdown time

GET /timers/{timer_id}/status is the endpoint you call when you render. The remaining time is computed on the server from the authoritative clock, so a browser with the wrong system time, a phone that was asleep, and a server-rendered page all agree.

curl https://countdownshare.com/api/v1/timers/$TIMER_ID/status \
  -H "Authorization: Bearer $COUNTDOWNSHARE_API_KEY"

{
  "data": {
    "status": "scheduled",
    "server_time": "2029-12-28T14:00:00.000Z",
    "target_at": "2030-01-01T14:00:00.000Z",
    "timezone": "UTC",
    "remaining": {
      "total_seconds": 345600,
      "days": 4,
      "hours": 0,
      "minutes": 0,
      "seconds": 0
    },
    "progress": 0.87,
    "ended": false
  },
  "request_id": "7b82b7f7-4d13-497b-9f20-58d46fd7a510"
}

Status values

Rendering it in JavaScript

A common pattern: fetch the authoritative remaining time once on load or on the server, then tick locally between fetches so the UI stays smooth without hammering the API.

export async function remainingTime(timerId) {
  const response = await fetch(
    `https://countdownshare.com/api/v1/timers/${timerId}/status`,
    {
      headers: {
        Authorization: `Bearer ${process.env.COUNTDOWNSHARE_API_KEY}`,
      },
      cache: "no-store", // the point of this call is that it is fresh
    },
  );

  const { data } = await response.json();
  return data.ended ? 0 : data.remaining.total_seconds;
}

Update, control, duplicate, and delete

Managing an existing timer never counts against your monthly allowance. Updates use optimistic concurrency: send the timer's current revision in an If-Match header and the API rejects the write if the timer changed since you read it.

Update a countdown

Send only the fields that change. At least one is required. Omitted fields keep their current values.

curl -X PATCH https://countdownshare.com/api/v1/timers/$TIMER_ID \
  -H "Authorization: Bearer $COUNTDOWNSHARE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Match: 1" \
  -d '{ "deadline_at": "2030-01-02T09:00:00-05:00" }'

curl -X POST \
  https://countdownshare.com/api/v1/timers/$TIMER_ID/actions \
  -H "Authorization: Bearer $COUNTDOWNSHARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "pause" }'

# start · pause · resume · reset
# Duration timers only.

Duplicate, archive, restore, delete

Embeds and hosted pages

GET /timers/{timer_id}/outputs returns every way to display a timer. The JSON status URL is always present. The hosted page, website embed, and email image are returned for published Production timers and are null otherwise — including for every Sandbox timer.

Countdown webhooks

Webhooks replace polling. Register a destination once, then attach rules to the timers you care about. When a rule matches, we send a signed HTTPS POST to your endpoint and retry it if your service does not answer.

curl -X POST \
  https://countdownshare.com/api/v1/webhook-destinations \
  -H "Authorization: Bearer $COUNTDOWNSHARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order automation",
    "url": "https://example.com/webhooks/countdownshare",
    "enabled": true
  }'

{
  "data": {
    "id": "0f4726a4-c05b-4eba-97d2-30ba8e59446e",
    "name": "Order automation",
    "url": "https://example.com/webhooks/countdownshare",
    "enabled": true,
    "signing_secret_prefix": "whsec_1a2b",
    "signing_secret": "whsec_...",
    "secret_rotated_at": "2029-12-01T10:00:00.000Z",
    "created_at": "2029-12-01T10:00:00.000Z",
    "updated_at": "2029-12-01T10:00:00.000Z"
  },
  "request_id": "7b82b7f7-4d13-497b-9f20-58d46fd7a510"
}

curl -X POST \
  https://countdownshare.com/api/v1/timers/$TIMER_ID/webhook-rules \
  -H "Authorization: Bearer $COUNTDOWNSHARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "One hour remaining",
    "webhook_destination_id": "0f4726a4-c05b-4eba-97d2-30ba8e59446e",
    "condition": {
      "field": "remaining_seconds",
      "operator": "less_than_or_equal",
      "value": 3600
    },
    "delivery": "once"
  }'

POST /webhooks/countdownshare HTTP/1.1
Content-Type: application/json
X-CountdownShare-Event-Id: d59cf3d3-a20c-46bf-b187-c27cd6ff51e2
X-CountdownShare-Timestamp: 1893506400
X-CountdownShare-Signature: v1=9f86d0818...

{
  "id": "d59cf3d3-a20c-46bf-b187-c27cd6ff51e2",
  "type": "timer.rule.matched",
  "occurred_at": "2030-01-01T13:00:00.000Z",
  "delivery_id": "0ec5af80-1125-43c8-9b72-04706b6da54a",
  "timer": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Product launch",
    "type": "fixed",
    "status": "published"
  },
  "rule": {
    "id": "264f4933-c839-47b5-a7ba-55a73ed56774",
    "name": "One hour remaining"
  },
  "data": {
    "status": "running",
    "remaining_seconds": 3600,
    "progress_percent": 99.86,
    "server_time": "2030-01-01T13:00:00.000Z"
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

// Express: app.post(path, express.raw({ type: "application/json" }), handler)
// The signature covers the RAW body. Parsing it first will break the check.
export function verify(rawBody, headers, secret) {
  const timestamp = headers["x-countdownshare-timestamp"];
  const signature = headers["x-countdownshare-signature"];
  if (!timestamp || !signature) return false;

  // Reject anything older than five minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const received = signature.replace(/^v1=/, "");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Dates and timezones

Fixed deadlines are exact instants. Recurring schedules are local wall-clock times that need a zone. Durations are elapsed time and need neither.

Get the exact supported list

GET /timezones is the source of truth for values this API accepts. Use it to build a selector or validate input, with the optional search query to filter. Runtime lists such as Intl.supportedValuesOf('timeZone') in JavaScript, zoneinfo.available_timezones() in Python, and ZoneId.getAvailableZoneIds() in Java vary by installed database version, so use them for your UI and this endpoint for validation.

GET /timezones?search=kolkata

{
  "data": [{ "id": "Asia/Kolkata" }],
  "meta": {
    "default": "UTC",
    "source": "IANA Time Zone Database"
  },
  "request_id": "7b82b7f7-4d13-497b-9f20-58d46fd7a510"
}

Countdown API error codes

Every error carries a stable machine-readable code, a human-readable message, and the request_id that also appears in the X-Request-Id response header. Quote that ID when contacting support.

HTTP/1.1 400 Bad Request
X-Request-Id: 7b82b7f7-4d13-497b-9f20-58d46fd7a510

{
  "error": {
    "code": "validation_error",
    "message": "deadline_at must be an ISO 8601 date-time with Z or a numeric UTC offset"
  },
  "request_id": "7b82b7f7-4d13-497b-9f20-58d46fd7a510"
}

Rate limits and usage

There is no monthly cap on API requests on any plan. A per-minute rate limit protects the service — 300 requests per minute in Production and 30 in Sandbox — counted per key and per account in a fixed one-minute window.

Check usage from the API

GET /usage reports the current billing cycle and every metered metric. GET /usage/requests returns your API request log, filterable by status, route, key, and request ID.

GET /usage

{
  "data": {
    "environment": "production",
    "cycle": {
      "id": "3f9d6a2c-...",
      "starts_at": "2030-01-01T00:00:00.000Z",
      "resets_at": "2030-02-01T00:00:00.000Z"
    },
    "metrics": [
      {
        "metric": "new_timers",
        "total": 214,
        "limit": 1000,
        "remaining": 786,
        "warning_threshold": 0,
        "starts_at": "2030-01-01T00:00:00.000Z",
        "resets_at": "2030-02-01T00:00:00.000Z"
      },
      {
        "metric": "api_requests",
        "total": 48213,
        "limit": "unlimited",
        "remaining": "unlimited",
        "warning_threshold": 0,
        "starts_at": "2030-01-01T00:00:00.000Z",
        "resets_at": "2030-02-01T00:00:00.000Z"
      }
    ]
  },
  "request_id": "7b82b7f7-4d13-497b-9f20-58d46fd7a510"
}

Requests, retries, and pagination

The same conventions apply across every endpoint, so behavior you learn once holds everywhere.

GET /timers?limit=25&sort=-created_at

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Product launch",
      "type": "fixed",
      "status": "published"
    }
  ],
  "page": {
    "has_more": true,
    "next_cursor": "eyJ2YWx1ZSI6Ii4uLiJ9"
  },
  "request_id": "7b82b7f7-4d13-497b-9f20-58d46fd7a510"
}