API Reference

Authentication

All API requests require a Bearer token in the Authorization header. Get your API key from the Dashboard.

Authorization: Bearer YOUR_API_KEY

Base URL & Headers

Base URL: https://castimer.com/api/v1

Endpoints

curl -X GET https://castimer.com/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST https://castimer.com/api/v1/timers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Meeting Timer",
    "type": "countdown",
    "duration": 1800
  }'

curl -X GET https://castimer.com/api/v1/timers/tmr_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X PATCH https://castimer.com/api/v1/timers/tmr_abc123/state \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "state": "running" }'

curl -X DELETE https://castimer.com/api/v1/timers/tmr_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Codes

Rate Limits

SDK & Libraries

Official and community SDKs for popular languages and frameworks.

Widget URL Format

The widget is served at a single URL with query parameters for configuration:

https://castimer.com/widget?type=countdown&title=My+Timer&duration=300&theme=dark&primary_color=6C63FF&lang=en

Parameters Reference

iframe Integration

Embed the widget using a standard iframe element:

<iframe
  src="https://castimer.com/widget?type=countdown&duration=300&theme=dark"
  style="width:360px;height:360px;border:none;"
  loading="lazy"
  title="Countdown Timer"
></iframe>

Embed Generator Tool

Use our visual Embed Generator to configure your widget and generate iframe code instantly. No need to manually construct URLs.

Get real-time notifications when timer events occur. For full documentation, see the Webhooks Guide.

Overview

Webhooks let Castimer notify your server in real-time when a timer event occurs — such as start, pause, or completion. Register a webhook URL when creating or updating a timer.

Event Types

Payload Format

{
  "event": "timer.completed",
  "timestamp": "2026-05-10T14:30:00Z",
  "timer_id": "tmr_abc123xyz",
  "title": "Flash Sale Countdown",
  "type": "event",
  "data": {
    "state": "completed",
    "duration": 1800,
    "actual_duration": 1803,
    "started_at": "2026-05-10T14:00:00Z",
    "completed_at": "2026-05-10T14:30:00Z"
  },
  "signature": "sha256=a8f3b2c..."
}

Signature Verification

Castimer signs each webhook with HMAC-SHA256. The signature is included in the X-Castimer-Signature header.

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return `sha256=${expected}` === signature;
}

Retry Behavior

If your endpoint returns a non-2xx response or times out, Castimer retries with exponential backoff:

Create Your First Timer

1. 1Get your API key from the Dashboard
2. 2Create a timer via the API:

curl -X POST https://castimer.com/api/v1/timers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Timer",
    "type": "countdown",
    "duration": 300
  }'

3. 3Use the returned timer ID to control it (start, pause, etc.)

Embed a Widget

1. 1Open the Embed Generator
2. 2Configure your timer settings visually
3. 3Copy the generated iframe code and paste it into your website

Set Up Webhooks

1. 1Create an endpoint on your server to receive POST requests
2. 2Include webhook_url when creating a timer
3. 3Verify the HMAC-SHA256 signature on incoming requests

curl -X POST https://castimer.com/api/v1/timers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Webhook Timer",
    "type": "countdown",
    "duration": 60,
    "webhook_url": "https://yourapp.com/webhooks/castimer"
  }'