API Documentation

ChronoShield API is a REST API that validates, resolves, and converts datetimes across timezones with explicit handling of DST ambiguity. It catches the edge cases that cause silent production bugs — invalid times that don't exist (spring-forward gaps) and ambiguous times that occur twice (fall-back overlaps).

Not needed for simple UTC display formatting. Built for apps that interpret and act on user-entered local times.

Real-World Scenarios

These are the exact situations where timezone bugs happen in production. Here's how ChronoShield API prevents each one.

Quick Start

Get your first timezone-safe API call working in under 2 minutes:

1. Get a free API key — enter your email on the home page (no credit card required)
2. Copy the curl command below — replace YOUR_API_KEY with your key
3. Run it — you'll get back a DST gap detection with suggested fixes

curl -X POST https://chronoshieldapi.com/v1/datetime/validate \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "local_datetime": "2026-03-08T02:30:00",
    "time_zone": "America/New_York"
  }'

{
  "status": "invalid",
  "reason_code": "DST_GAP",
  "message": "This time does not exist due to DST transition.",
  "suggested_fixes": [
    { "strategy": "next_valid_time", "local_datetime": "2026-03-08T03:00:00" },
    { "strategy": "previous_valid_time", "local_datetime": "2026-03-08T01:59:59" }
  ]
}

Authentication

All /v1/* endpoints require an API key via the x-api-key header:

x-api-key: cg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Getting a key

1. Visit the landing page and click "Get Free API Key"
2. Enter your email — a key prefixed with cg_live_ is generated instantly
3. Store it securely — it won't be shown again

Tiers

Enterprise plans include invoice billing, SLA response times, and declining overage rates. Full pricing details →

Starter — best for one team needing annual billing & SLAs. Growth — best for multi-product or high-volume SaaS. Strategic — custom volume, dedicated environments, procurement & legal support.

Unauthorized response

HTTP 401
{ "error": "Unauthorized: invalid or missing API key" }

Check whether a local datetime is valid, invalid (DST gap), or ambiguous (DST overlap) in the given timezone.

When to use: Before storing or acting on a user-provided local time. Call this first to detect problems, then decide how to handle them — or use /resolve to handle them automatically.

Request body

Response — valid time

{
  "status": "valid",
  "message": "The provided datetime is valid in the given timezone."
}

Response — DST gap (invalid)

{
  "status": "invalid",
  "reason_code": "DST_GAP",
  "message": "This time does not exist due to DST transition.",
  "suggested_fixes": [
    { "strategy": "next_valid_time", "local_datetime": "2026-03-08T03:00:00" },
    { "strategy": "previous_valid_time", "local_datetime": "2026-03-08T01:59:59" }
  ]
}

Response — DST overlap (ambiguous)

{
  "status": "ambiguous",
  "reason_code": "DST_OVERLAP",
  "message": "This time is ambiguous due to DST transition (fall-back).",
  "possible_instants": [
    { "offset": "-04:00", "instant_utc": "2026-11-01T05:30:00.000Z" },
    { "offset": "-05:00", "instant_utc": "2026-11-01T06:30:00.000Z" }
  ]
}

Response — invalid timezone

{
  "status": "invalid",
  "reason_code": "INVALID_TIMEZONE",
  "message": "Invalid IANA timezone: Fake/Zone"
}

Resolve a local datetime to a single UTC instant, automatically handling DST gaps and overlaps using your specified policy.

When to use: When you need a definitive UTC timestamp from a local time and want deterministic behavior for edge cases.

Request body

Resolution policies

Example request

{
  "local_datetime": "2026-11-01T01:30:00",
  "time_zone": "America/New_York",
  "resolution_policy": {
    "ambiguous": "earlier",
    "invalid": "next_valid_time"
  }
}

Success response

{
  "instant_utc": "2026-11-01T05:30:00.000Z",
  "offset": "-04:00"
}

Rejected response (policy = reject)

HTTP 400
{
  "error": "This time is ambiguous due to DST transition and policy is set to reject.",
  "code": "DST_OVERLAP"
}

Convert a UTC instant to a local datetime in the target timezone. This is always unambiguous — one UTC instant maps to exactly one local time.

When to use: Displaying stored UTC timestamps to users in their local timezone.

Request body

Example

{
  "instant_utc": "2026-06-15T15:00:00Z",
  "target_time_zone": "Europe/London"
}

{
  "local_datetime": "2026-06-15T16:00:00",
  "offset": "+01:00",
  "time_zone": "Europe/London"
}

Process up to 100 validate, resolve, and convert operations in a single request.

When to use: Importing calendar events, migrating scheduling data, or any scenario where you need to check multiple datetimes at once. Partial failures are handled gracefully — each item succeeds or fails independently.

curl -X POST https://chronoshieldapi.com/v1/datetime/batch \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "items": [
      { "operation": "validate", "local_datetime": "2026-03-08T02:30:00", "time_zone": "America/New_York" },
      { "operation": "resolve", "local_datetime": "2026-11-01T01:30:00", "time_zone": "America/New_York", "resolution_policy": { "ambiguous": "earlier" } },
      { "operation": "convert", "instant_utc": "2026-06-15T15:00:00Z", "target_time_zone": "Europe/London" }
    ]
  }'

{
  "results": [
    { "index": 0, "operation": "validate", "success": true, "data": { "status": "invalid", "reason_code": "DST_GAP", ... } },
    { "index": 1, "operation": "resolve", "success": true, "data": { "instant_utc": "2026-11-01T05:30:00.000Z", "offset": "-04:00" } },
    { "index": 2, "operation": "convert", "success": true, "data": { "local_datetime": "2026-06-15T16:00:00", "offset": "+01:00" } }
  ],
  "total": 3,
  "succeeded": 3,
  "failed": 0
}

Request fields

Each item includes the same fields as its respective individual endpoint. Failed items return success: false with an error object.

Returns service health status. No authentication required.

{ "status": "ok" }

Enums & Constants

status

reason_code

Error Handling

All errors return JSON with an error field and an appropriate HTTP status code.

Validation error example

HTTP 400
{
  "error": "Validation failed",
  "details": [
    {
      "code": "invalid_string",
      "message": "Must be ISO 8601 local datetime (e.g. 2026-03-08T02:30:00)",
      "path": ["local_datetime"]
    }
  ]
}

Rate Limits

All endpoints use pure computation with cached timezone lookups — no external I/O in the request path.

Official SDKs

Maintained by the ChronoShield API team. SDK packages will be published to npm and PyPI soon — in the meantime, you can use the API directly via HTTP or copy the SDK source from GitHub.

TypeScript / JavaScript

import { ChronoShieldClient } from "chronoshield";

const client = new ChronoShieldClient({
  baseUrl: "https://chronoshieldapi.com",
  apiKey: "YOUR_API_KEY",
});

const result = await client.validate({
  local_datetime: "2026-03-08T02:30:00",
  time_zone: "America/New_York",
});

console.log(result.status); // "invalid"

Python

from chronoshield import ChronoShieldClient

client = ChronoShieldClient(
    base_url="https://chronoshieldapi.com",
    api_key="YOUR_API_KEY",
)

result = client.validate("2026-03-08T02:30:00", "America/New_York")
print(result.status)  # "invalid"

AI Agent / Tool Integration

ChronoShield API exposes tool schemas compatible with function-calling AI agents (OpenAI, Anthropic Claude, LangChain, CrewAI, etc.). Download the schemas from agent-tools.json.

Available tools

Example: AI scheduling assistant