API Documentation

Pro+

Programmatically create and manage countdown timers with the SnapTimers API.

Quick Start

1. Get your API keyPro+

Create an API key from your account settings. API access is available on Pro, Business, and Enterprise plans.

2. Make your first request

Include your API key in the Authorization header:

bash

curl https://www.snaptimers.com/api/v1/timers \
  -H "Authorization: Bearer st_your_api_key_here"

Authentication

All API requests require authentication using your API key. Include it in the request headers:

http

Authorization: Bearer st_your_api_key_here

Alternatively, you can use the X-API-Key header.

Rate Limits

API requests are rate limited to ensure fair usage:

60 requests per minute per API key
10,000 requests per day per API key

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Endpoints

GET/api/v1/timerstimers:read

List all timers

POST/api/v1/timerstimers:write

Create a new timer

GET/api/v1/timers/:idtimers:read

Get timer details

PATCH/api/v1/timers/:idtimers:write

Update a timer

DELETE/api/v1/timers/:idtimers:write

Delete a timer

GET/api/v1/timers/:id/analyticsanalytics:read

Get timer analytics

GET/api/v1/usageusage:read

Get usage statistics

Create a Timer

POST/api/v1/timers

Create a new countdown timer with custom styling.

javascript

const response = await fetch('https://www.snaptimers.com/api/v1/timers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer st_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Flash Sale Timer',
    type: 'fixed',
    targetDate: '2024-12-25T00:00:00Z',
    timezone: 'America/New_York',
    template: 'bold',
    colors: {
      background: '#1a1a2e',
      text: '#ffffff',
      accent: '#ff6b6b',
    },
  }),
});

const { data } = await response.json();
console.log(data.embedUrl);
// https://cdn.snaptimers.com/t/abc-123.gif

Response Format

All responses are JSON and follow this structure:

json

{
  "data": {
    "id": "abc-123-def-456",
    "name": "My Timer",
    "type": "fixed",
    "status": "active",
    "targetDate": "2024-12-25T00:00:00Z",
    "viewCount": 1542,
    "embedUrl": "https://cdn.snaptimers.com/t/abc-123.gif",
    "embedCode": "<img src=\"...\" alt=\"Countdown Timer\" />"
  }
}

Error Handling

Errors return appropriate HTTP status codes with details:

json

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Common Error Codes

401Invalid or missing API key

403Insufficient permissions or plan

404Resource not found

429Rate limit exceeded

Ready to get started?

API access is available on Pro, Business, and Enterprise plans.