Sign upCreate account Log in

Create account Log in

Countdown Timer API Documentation

Everything needed to create a countdown with the REST API, read its remaining time from an authoritative server clock, control duration timers, and receive signed webhook events. Every example is plain HTTP against the live API — there is no SDK to install and nothing to compile.

Base URL: https://countdownshare.com/api/v1
Protocol: REST over HTTPS, JSON
Authentication: Bearer API key
Environments: Sandbox · Production

OpenAPI 3.1 specification

Import the spec into Postman or Insomnia, or generate a typed client in your language. It is public and needs no key.

Download openapi.yaml

The whole API in one request

Creating a timer returns an ID. Every other call in this documentation takes that ID. If you read nothing else, read the quick start and this snippet.

Your first request

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

Browse the documentation

Read straight through in this order, or jump to what you need. Each page ends with a link to the next one.

Get started

Quick startIssue a Sandbox key and create your first countdown in three requests.AuthenticationBearer API keys, what the cs_test_ and cs_live_ prefixes mean, and how to rotate safely.Sandbox and ProductionWhat differs between the two environments and what to check before you go live.

Core concepts

Timer typesFixed, duration, recurring, and personalized — and how to pick the right one.Requests and responsesThe response envelope, the headers on every call, and how versioning works.Pagination and filteringCursor pagination, sorting, filters, and a safe loop for reading every timer.IdempotencyWhy creation needs an Idempotency-Key, and how to choose one that actually protects you.Dates and timezonesWhen a timezone matters, when it is ignored, and which identifiers are accepted.

Countdown timers

Endpoint referenceEvery timer endpoint in one table, with the shape of the timer object.Create a timerPOST /timers field by field, with the rules each timer type adds.Read remaining timeThe status endpoint, the four status values, and how to render without clock drift.Update and deleteOptimistic concurrency with If-Match, plus duplicate, archive, restore, and delete.Control duration timersStart, pause, resume, and reset — the four actions and what each does to remaining time.Recurring timersDaily, weekly, monthly, and RRULE schedules, and how cycles roll over.Personalized timersA separate deadline per recipient, fixed at creation — evergreen deadlines via API.Embeds and hosted pagesHosted page, website embed, email GIF, and JSON — what each returns and when.

Webhooks

Webhooks overviewDestinations, rules, and deliveries — the three pieces and how they fit together.DestinationsRegister a URL, receive a signing secret, test it, and rotate without downtime.RulesThe six conditions a rule can watch, and when to use once versus repeat.Events and payloadEvery event type, the delivery headers, and the body your endpoint receives.Verify a deliveryHMAC-SHA256 verification against the raw body, with working code and the usual mistakes.Retries and replayThe retry schedule, delivery statuses, and how to replay a failed delivery.

Reference

Error codesEvery code the API returns, the HTTP status beside it, and what to do about each.Rate limits and usageThe per-minute limit, the monthly timer allowance, and reading both from /usage.

Ready to connect your first countdown?

Sandbox is free with any account and needs no plan. When you are ready to publish, pick a plan and swap your cs_test_ key for a cs_live_ one.

Create an account View API pricing

All documentation